Reimplement Resource._setup_local_to_scene & deprecate signal

[Mickeon]

Requires #81388.

This PR reimplements the virtual method Resource._setup_local_to_scene, that has been lost since #51970. It also gives it a much, much better description compared to 3.x:

Finally, deprecates the now redundant setup_local_to_scene_requested signal.
This signal can only be useful when connecting it in the custom Resource's own _init. It can be called manually with setup_local_to_scene. However, whether or not setup_local_to_scene should be exposed to the user in the first place is very up to debate to me (see my struggles attempting to update the description in #67072 and #67082.

I wish I could just remove it, to be honest. Only like, one or two people in the universe may be using it.

[Mickeon]

Rebased. Bumping this up.

[KoBeWi]

The signal should be deprecated (and still functional) instead of being removed.
Also it should be a proper virtual method with GDVIRTUAL_BIND/CALL.

[Mickeon]

So, wait, is the implementation on the PR not quite right? How to go about it?

[KoBeWi]

This part is wrong:

if (get_script_instance()) {
	Callable::CallError ce;
	get_script_instance()->callp(SNAME("_local_to_scene_setup"), nullptr, 0, ce);
}

All virtual calls should now use GDVIRTUAL_CALL() (AFAIK it's related to GDExtension).

Then again, I see some methods still called via get_script_instance(), so I'm not sure if it's legacy or there are cases where it should be used 🤔

[Mickeon]

This PR has been updated to to work with GDExtension, because the cyclic dependency has been thankfully solved.

It also is no longer compatibility-breaking, because the signal is deprecated, but functionality is still retained (to my dismay).

[YuriSizov]

renames it to _local_to_scene_setup to better suit other similar virtual methods

Can you give an example? Typically a virtual method that needs to be implemented to change the behavior of a non-virtual methods is called exactly the same with the _ prefix.

[Mickeon]

Can you give an example? Typically a virtual method that needs to be implemented to change the behavior of a non-virtual methods is called exactly the same with the _ prefix.

I'm not sure why I made that decision last year. It's likely because _local_to_scene_setup sounded more natural. It's the method where the setup takes place, and...

In hindsight I can't explain a good reason to keep it. Perhaps this is because virtual method names may have been standardized more across the board.
I could just bring back the old virtual method as it was without any conversion. I'm surprised no one mentioned it until the last second.

[YuriSizov]

I'm surprised no one mentioned it until the last second.

Well, we got to reviewing this PR only a few weeks back :P And it's more of a codestyle pass thing, while previous comments were about the implementation.

[Mickeon]

Update the PR to change the name back to 3.x's equivalent.

Modified the description of _setup_local_to_scene slightly because I wasn't quite happy with it.
And added a deprecated message underneath setup_local_to_scene and setup_local_to_scene_requested.

[KoBeWi]

What "excluding the original" refers to? I did a test with this method in a tool script and every Resource instance has this called.

EDIT:
I used this for testing:
LocalTest.zip

[Mickeon]

"Excluding the original" refers to the resource every local resource has been duplicated from. The method is called on every new one, but the original Resource, basically the following in your scene, is not affected by this:

[sub_resource type="Resource" id="Resource_gw2eg"]
resource_local_to_scene = true
script = ExtResource("1_khad7")
damage = 0

You may actually change this Resource at run time without affecting the duplicates. However, every newly instantiated scene will create its own local resources with the original properties in mind.
This is worth knowing especially for Resources like Stylebox, or resources saved to disk.

Under the hood you may If you also feel like this is necessary information and/or have better ways to phrase it, feel free to suggest.

[KoBeWi]

But if I open HolderOfLocal.tscn and save it, it will be modified. If I run the scene and print the value, it will also have a different value.

@export var res: Resource

func _ready() -> void:
	print(res.damage)

So when this method doesn't get called?

[Mickeon]

That is... unexpected. Oh dear.
For now I'll remove the "except" stuff, but that feels like should not happen. Maybe this bug, if it is one, only happens when a Resource is contained within a PackedScene?

[Mickeon]

The final stretch.

I'm leaving that conversation unsolved because it intrigues me.

[akien-mga]

Thanks!