Vector2.move_toward() unexpected behaviour not documented.

[CitrusWire]

Your Godot version: 3.2.3

Issue description: `move_toward(), moves the unit in relation to its own local coordinate system rather than the world or even just scene coordinate system. This may be unexpected / undesired for some users but isn't documented.

Edit: Using global_position rather than position works around this. Could be worth highlighting too.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/classes/class_vector2.html#class-vector2-method-move-toward

[YuriSizov]

I fail to understand what kind of behavior you would expect. It's an isolated operation on two vectors. Values are absolute. There is no relation to any particular coordinate system. This is true for any vector math operation.

If you happen to get a vector from the outside of a node and want to do something about it's position in relation to that node, you first need to convert your vector to that node's coordinate system. There is no trick specific to move_towards, it's a very straightforward function.

[CitrusWire]

While you are clearly very proficient with Vectors, not all of us are. I appreciate your explanation but you have to remember not everyone knows what you know. That's what the docs are for. Godot has a lot of gotchas; Things that are "obvious" to those who are au fait with C(++) and game engines but less so for those of us coming from a higher level world, and/or with less maths. If I find it non-obvious with my background I figure there's an excellent chance others will too.

Edit: To answer the question: I figured it would be similar to move_and_slide; move_and_collide. I can see why it's not now, but it's an easy thing to miss.

[YuriSizov]

move_and_slide and move_and_collide are methods of nodes, and spatial nodes at that. move_towards is a method of a vector. A vector is a data type. Data types are unaware about the circumstances and contexts they are being used in. A number 4 doesn't know what it is being used for — a number of enemies, health points, octaves of a simplex noise or colors of rainbow. Data is by its nature oblivious to the way it is used. It is raw and absolute. It's the job of the user to provide the necessary context and adapt the data if necessary. Nodes on the other hand are completely aware about their spatial properties and can use that for relative manipulations.

The class reference for the Vector2 does not state these facts about data types explicitly, because it is a given for any data type. Indeed, one can say that this is a thing that programmers are aware of and someone unexperienced with programming may not be. But, as of the most recent version of the docs, we've opted out of teaching programming in Godot docs and instead require users to learn the ropes at Harvard's CS50 course. This is more efficient than trying to teach CS basics ourselves and doing a poor job at that. The course is considered a good introduction into the matter though.

So back to your particular issue. The only commonality between move_and_slide and move_towards is the use of the word "move". This of course may cause some confusion on the surface level, especially if the reader is unexperienced with reading code, code documentation or just misses the fact that one is a Node and the other is data. You can propose renaming move_towards to reduce this collision of meanings, but you would need to provide a better name for it and a solid reason for breaking compatibility. However, I do not believe that this particular method has a problematic description regarding its application. And this knowledge applies to all of Vector2's method, as well as methods of other data types.

At the end of the day this boils down to the fact that each person comprehends the information in a different manner, but we cannot address each and every misunderstanding users have in the docs. This is beyond the scope of the class reference, unfortunately. This is, however, a perfect case to ask a question in one of our community channels. People come in with misunderstandings all the time, and this is what our community can help to resolve quickly. This kind of help is also very personal, so you can get answers very specific to your problems.

[CitrusWire]

This is beyond the scope of the class reference, unfortunately.

Here I must disagree. This is exactly what the class reference is for. To tell people not only what something /is/ but in common cases, what it's is not, and ideally(!) what the alternatives are.

Area2D for example has these notes scattered through it:

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

... (different method))...

This makes selecting the areas scanned easier.

Or AnimatedSprite (Stop):

Stop the current animation (does not reset the frame counter).

Or Translation:

Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use affine_inverse for transforms with scaling).

etc etc.

In this case not only should move_toward be documented in this respect, it should point to a page with a list of all the ways to move stuff; as should all the other moving functions. Coincidentally a while back I opened a ticket pointing out that movement tutorial doesn't actually cover movement!

The problem with not documenting these gotchas is that they cause pain-points. I'm finding multiple ones per day and each of them stops me in my tracks for a while. I've learn many, many pieces of software over the years, but Godot is definitely at the high end for Gotchas. Another one for today (https://github.com/godotengine/godot/issues/44996) I reported as a bug, Calinou flags it as a bug, but KoBeWi said it's intentional and closed it. This is was also something that should be in the docs and in a moment I'll add a proposal for it.

If you want to see good API documentation look at PHP. The docs are great at documenting the (many!) quirks the language has. There are two notes on something as basic as array_slice for example: https://www.php.net/manual/en/function.array-slice.php And they've been this good for at least 20 years now (as in, when PHP was younger than Godot is now!).

This is, however, a perfect case to ask a question in one of our community channels.

I do appreciate the suggestion but I'm already on the IRC. And actually I did ask about whether this was intended behaviour on the -devel channel but no-one bothered replying, so I went ahead with this.

Ignoring that though, there are other problems with repying on the community channels for things that should be in the docs:

• Asking something and waiting for a reply delays things and you lose track of where you are in the process if it's a blocker.
• Scalability (and taking people's time). Imagine 10 people all have this one gotcha - that's 10 conversations versus taking at least 20 peoples time. Now what if 100 people hit this? And that's per gotcha.
• What about people who for whatever reason don't ask on the channels? Yesterday I saw a comment on something about how someone had spent an entire day trying to figure out why their raycast didn't work. Turns out they're disabled by default and they didn't know that. That's an entire person-day wasted because of some combination of odd-design-choice and not-documenting said choice. I know I'd be much faster debugging it (it only took me about 5-10 minutes to get around the similar adding-a-camera-doesn't-just-work gotcha), and I suspect you would be too, but again, different people are at different levels and Godot markets itself as "Easy to program".

[YuriSizov]

In this case not only should move_toward be documented in this respect, it should point to a page with a list of all the ways to move stuff; as should all the other moving functions.

This is not a function that actually moves stuff. This is a function that changes a vector alongside a line between it and another point in space. It's not a movement operation, it's just math. Which is why I suggested you, as you were confused by the use of the word "move", to propose a rename.

The problem with not documenting these gotchas is that they cause pain-points.

There is no gotcha. It is plain and simple. Data doesn't know how you use it. Data is just data. Vector2 is just two floats that represent a point in some arbitrary space. However you use it, it doesn't have any clue. It is not aware of a node you put it into or a node you've taken it from. Passing a variable between nodes does not magically transform it. I struggle to imagine what do you propose we add to the description of each Vector2 method. "Be mindful of the values you use and don't forget to make sure they are relative to the same space"? I don't know, this sounds confusing to me, unless you come to the docs with your specific issue.

Again, you are complaining that VectorA + VectorB does not respect the fact that you took VectorA relative to NodeA and you took VectorB relative to NodeB. This kind of thing is covered by tutorials, not by the class reference of Vector2 methods. It's unrelated to them. And as such is out of scope for the class reference all together.

I do appreciate the suggestion but I'm already on the IRC.

Our Discord community is by far more active. Just saying.

I reported as a bug, Calinou flags it as a bug, but KoBeWi said it's intentional and closed it. This is was also something that should be in the docs and in a moment I'll add a proposal for it.

Calinou only marked it as a bug at first, before you produced a project to test your claims. As you did so, KoBeWi looked into it and gave you a more appropriate answer. As you can see now, the bug label was removed, because the issue was indeed on your end, not in the engine. And please, don't waste your time writing a proposal for your misunderstandings. There is no point. As there is no point to document every detail a beginner in programming or game development may face. They will face it anyway. And they will ask for help, and likely they will receive it. This is normal.

The docs for PHP that you mention are actually pretty mediocre. They are fine, but to a point. However where they shine is in community comments that actually detail those quirks of the language and the runtime, but it's not in the docs themselves. Because docs will always be dry and sometime they may confuse you, and this is where you ask a human being for help, and they will explain it to you with the words that you specifically would understand.

In the same vein as PHP doc comments we have the Q&A platform, you can ask there. There are even plans in work right now to integrate the Q&A into the online documentation, so that confusions could be solved by looking for other people asking the same questions. This is the appropriate way to deal with individual issues.

---

To stop this from becoming another endless debate, please provide an example of what would you put next to every Vector2 method to make sure people aren't as confused as you in future.

[Clonkex]

IMO this should be closed since it's user error.

[CitrusWire]

IMO this should be closed since it's user error.

It may be a user-error but that just emphasizes that maybe it's a documentation error too (or a design error, but that's probably not this case). You can't expect your users to be experts in the system, things have to be documented clearly.

I really don't get all of the "it's your mistake" when the ticket is clearly about clearing up the documentation so fewer people make this mistake. Is there some rule that Godot's documentation only be of a certain number of words/bytes? Do you want there to be a minimum skill-level to use Godot and you're trying to enforce that implicitly by refusing to clarify things in the documentation? I don't get this attitude.

[Clonkex]

I misread the title of your post so I misunderstood that you have an issue with the documentation; apologies for that.

I think it's perfectly reasonable for the docs to assume some level of familiarity with vector maths. You don't have to be "very proficient" with vectors, but at least understanding what a vector is and represents seems like a fair expectation (given that you only have to realise that it's literally just three numbers to understand that there's no such thing as a coordinate system in the context of a vector). It's possibly the simplest mathematical structure used in games and it's exceedingly common and well-known across all engines and dozens of disciplines. Godot won't teach you algebra, so there's already some minimum expectation there.

It sounds like I'm calling you stupid for not already knowing how vectors work, but what I'm trying to say is that whether you thought they were or not, vectors are about as basic as 3D maths gets, and it's not unreasonable to expect beginners to learn about vectors as part of learning how to create games. It's actually really critical to understand vectors: they're a fundamental mathematical tool in all game development and you won't get far without understanding them (which is fine, because they're really simple).

I've been where you've been. You might not believe me, but I remember exactly what it's like. I remember being just as confused as you about some topics, and just as frustrated that the docs didn't specifically account for not already knowing how the feature should work. I remember hating people for giving me mathematical answers without explaining what it meant, because I simply didn't have the background to understand. I don't want to dismiss your complaint because I know that just adds to the frustration, but I really want you to understand that it's a reality of being self-taught (making an assumption here) that you'll end up with unexplained gaps in your knowledge.

My point is that I don't think it's reasonable for Godot to try to cover every possible bit of confusion. The docs would become an overcomplicated mess. There's a balance between too little and too much documentation.

It's also worth pointing out that my voice has little weight here. I'm not a new developer but I'm new to Godot and have no control over what documentation gets updated; I'm just spouting my two cents. Feel free to ignore me; I won't be offended :)

[CitrusWire]

To be clear: I know what a vector is, at least academically. Or I did. I've learnt about them multiple times over the last few years (and probably cough years ago at school too), it's just that for whatever reason I don't retain/integrate that knowledge as well as I do information about countless other domains that I also dabble in. If you don't have a intuitive understanding of vectors, these things aren't obvious.

I'd further point out that far more effort has now been put into these responses than it would take to actually write the requested doc (For my part, I don't understand the issue well enough to contribute in that way).

[Clonkex]

I'd further point out that far more effort has now been put into these responses than it would take to actually write the requested doc

Oh of course, but it's not about effort. It's about whether or not it should be done - at least, in my limited view.

[skyace65]

Closing per Yuri and Clonkex's comments