Global_Position behavior inconsistencies

[zetim]

I recently encountered a situation where global_position did not behave as the global_position in any intuitive sense.

When you are in an _input() function and call the global_position value as a property of the event, you do not get the global_position relative to anything within your scene. If the root node moves, or a camera moves, the InputEvent.global_position does not change. This was explained to me as having something to do with the input being a node shooting off from root in a separate tree from the scene nodes, but it also seems possible that through each frame the game moves the global position before it starts placing any nodes from the scene tree, and then moves it back, and the incongruency arises from the timing of the calls.

Whatever the reason, one would expect that if you were to move a camera node that is child only to the scene's parent node, and have a visible object that moves on the screen, then calling InputEvent.global_position if the event is being triggered at that target should not be changing, but it does.

Here is the code to elucidate what I mean. You can examine the attached project file for your own testing.
test.zip
Parent of the scene is a Node2D
It has a child Node2D with the following script:

func _input(event: InputEvent) -> void:
	if event is InputEventMouseButton and event.button_index == 1 and event.pressed == true:
		var click_pos = event.position
		var click_pos_g = event.global_position
		print(click_pos,click_pos_g)

second child to the parent is a Camera2D with the following code:

func _process(delta):
	if Input.is_action_pressed("ui_up"):
		position += Vector2(0,-5)
	if Input.is_action_pressed("ui_down"):
		position += Vector2(0,5)
	if Input.is_action_pressed("ui_left"):
		position += Vector2(-5,-0)
	if Input.is_action_pressed("ui_right"):
		position += Vector2(5,-0)

and finally, a third child that's the default godot texture/image so you can see the effects of the camera moving.

The expected behavior I think for pretty much every user except those intimately familiar with the deep inner cores of the engine, is that as the camera moves and you keep on your mouse to click on the image, the position should change as you move, but the global position should stay the same- barring some margins of error for accuracy of the mouse. Alternatively, if you keep the mouse in the same spot and just move the camera as you click, the expectation is that the position shouldn't change, and the global should.

This does not happen.

No matter what you do, the global_position and position when called from the event stay the same value.

You can of course use the get_global_mouse_position() method and this works with the expected behavior above. However, this sort of betrays the fact that this lack of clarity on these properties exists.

I suggest a couple things.

Before any changes to the actual engine, clarity in the InputEvent class's documentation about global_position being a callable property seems like a good start. It doesn't seem to be an actual intrinsic property to the event(I think?), but you can call it, and it exists as a value. I would write out a proposal of the documentation itself, but I truly do not comprehend what is happening or why it would behave this way. It is a black box to me.

And more seriously, some indication to the user that this property is effectively entirely different from global_position in any other context. This could be a straight up error and not allowing the thing to compile? I'm not sure about that one as it might break an existing project that uses this, maybe there's a use case here that is way beyond my comprehension of the situation, but it seems like the position property should cover everything you'd want to do with positions from an InputEvent, as position and global_position values appear to never diverge, or at least don't diverge for any expected or intuitive reason.

Alternatively, renaming it to something else, such as viewport_position, seems like another fair solution. This may brick something within the engine with co-dependencies that are beyond my technical comprehension, so if I were the one modifying the engine I'd definitely be anxious about this, but honestly this would be my preferred solution as a game developer, and not an engine developer.

But the last solution I have in mind, and it seems like the softest-hand approach that would still technically be considered a solution, is to simply throw up a yellow warning when InputEvent.global_position is used inside an _input() function. It warns the user that "calling the global_position property on an InputEvent does not behave as expected", and can direct the user to new documentation explaining this incongruent behavior.

I'm sure there are a great many things about this property that I don't know that I don't know. I think that's part of the issue in general- the information is not easily available in the documentation where you'd expect to find it. Or it could be arcanely devised this way on purpose to address some other equally confounding issue. One of those comments in the code that says "Don't ask why this works" My primary perspective here is one of a game developer. I think with that lens, the current behavior almost rises to bug status, but with enough ambiguity on it that I refrained from reporting it as such.

I really would like to hear what people who are more knowledgeable about this entire piece of the system have to say about it. I would love to receive a cogent reply detailing exactly why it is this way and why it makes sense, if it is indeed behaving exactly as intended.

[theraot]

First, I want to get something out of the way: InputEvent is not a Node, that explanation you got is wrong. There is a kernel of truth is that input events will propagate across the scene tree, but that is not relevant here.

Also, where does it say to "Don't ask why this works", I can't find that.

---

Anyway, you are correct that global_position is not a property of InputEvent.

But since GDScript act as a dynamic language, global_position is late bound... Meaning it is resolved when the code runs. If the actual object has a global_position, it will use that, otherwise it is a runtime error.

And there is, as you might guess, a type of InputEvent that has a global_position: InputEventMouse. In your code, you are checking for InputEventMouseButton which is a subclass of InputEventMouse, so your usage checks out.

Now, let us look at the documentation of InputEventMouse.global_position:

When received in Node._input or Node._unhandled_input, returns the mouse's position in the root Viewport using the coordinate system of the root Viewport.

When received in Control._gui_input, returns the mouse's position in the CanvasLayer that the Control is in using the coordinate system of the CanvasLayer.

There is a logic to it. To make sense of it, have a look a the documentation of InputEventMouse.position:

When received in Node._input or Node._unhandled_input, returns the mouse's position in the Viewport this Node is in using the coordinate system of this Viewport.

When received in Control._gui_input, returns the mouse's position in the Control using the local coordinate system of the Control.

Did you catch the difference? The InputEventMouse.global_position is relative to the root Viewport, and InputEventMouse.position is relative to the Viewport the Node is in. If you do not have SubViewports, the Viewport the Node is in is the root Viewport, so I expect these two variables to be the same in that situation.

Well, in the case of Control._gui_input it is relative to the parent in the case of position, or the CanvasLayer in the case of global_position. So here it would be more common to have a difference.

---

I'm going to give you another reason to avoid InputEventMouse.global_position: Touch events don't have an equivalent. That is, InputEventGesture and InputEventScreenTouch have position but not global_position.

I'm going to guess this is oversight (I imagine that input emulation usually takes care of it, and the use case is rare enough, that it never came up).

Yet, this means, that if you want to write your code in a way that will handle both mouse and touch (without relying on input emulation) you are going to avoid global_position.

---

Why does InputEventMouse.global_position exist? I don't know. Looking at git blame, it was there when Godot became open source. Note: I haven't taken the time to see if it is used internally somehow (dragging Controls is what comes to mind, but as I said, I haven't checked).

---

And finally, what to do about it...

Renaming to viewport_position does not solve it, does it? The difference is not whether or not the position is relative to a Viewport but which one. And that is only when it is not in Control._gui_input, there it is not about the Viewport at all. Regardless, a property rename is a breaking change, so I'd expect the core developers to be reluctant to do it in a minor version.

At first I was going to say that a warning might not be great because there are legitimate use cases. But given that the use case is rare enough, and there aren't touch counterparts, I can't rule it out as an option.

In fact, unless the Godot team has other plans... My current opinion is that if it is necesary we could add methods with better names (and also for touch events to bring them on par), and the property can be deprecated.

I hope somebody from the Godot team can comment.

[theraot]

Godot will instantiate a subclass of InputEvent depending on the particular type of event it is reporting. The class of that object does not change. And the _input method can receive any of them. And that is what you are checking with event is InputEventMouseButton. I hope that makes sense.

[zetim]

Godot will instantiate a subclass of InputEvent depending on the particular type of event it is reporting. The class of that object does not change. And the _input method can receive any of them. And that is what you are checking with event is InputEventMouseButton. I hope that makes sense.

Okay- see, if that's how it works, I would expect to have to target the instantiated new class object with event.InputEventMouse.global_position, and not directly to the event. That I don't is what's confusing to me.

[theraot]

If you want Godot to complain about doing event.global_position you can enable the unsafe property access warning in project settings.

You can workaround said warning like this:

var mouse_event := event as InputEventMouseButton
if mouse_event == null:
    return

var click_pos_g := mouse_event.global_position
# ...

I do not recognize the syntax you suggest (event.InputEventMouse.global_position), what languages does this?

Anyway, GDScript began fully dynamic, which means that you would not (in fact, you could not) specify the types at all, and instead Godot would figure them out in runtime. And that is usually considered easier for beginners, and there is people who prefer it for quick prototyping, because it means they don't have to think about the class hierarchy or the variable types... With the drawbacks of worse autocomplete and making things harder to find in the documentation, and so on. I prefer static types, by the way. Addendum: I prefer the system to tell me when I'm doing something wrong as soon as possible, including not waiting to run the code to get an error.

[zetim]

I do not recognize the syntax you suggest (event.InputEventMouse.global_position), what languages does this?

Is InputEventMouse not a class extended from InputEvent? And earlier it was said that it instantiates from InputEvent itself when the event is of the type pertaining to a mouse. When you do this with nodes, this is the syntax. Maybe I'm thinking erroneously that the same syntax would apply here.

It doesn't bother me so much that the typing changes. What bothers me is that the global_position variable behaves different between nodes and non-nodes, and you really have to dig deep into the input documentation to find clues to piece it together. I've learned this lesson now after spending a decent amount of time delving into it and with everyone here's and people on the discord's help. What I'd like to see happen is the default user experience for someone new not have to encounter this and get as confused as I did.

[theraot]

Yes, InputEventMouseButton is a subclass of InputEventMouse, which is a subclass of InputEvent.

In fact, I'm skipping some classes there, it goes like this: InputEventMouseButton < InputEventMouse < InputEventWithModifiers < InputEventFromWindow < InputEvent < Resource < RefCounted < Object

---

I agree that having global_position mean something different is not good.