Migrate Vector3 to vector

[CadeusTheGreat]

Introduction

With the introduction of the Vector RFC seen in the release notes for 650

Changes

This PR migrates the documentation of Vector3 references to the new vector library where appropriate. Some references may need changing back due to the change required explained next.

More changes may be needed to make this request make sense to end users. Such as a dedicated page in the documentation for - the new library (Raised in PR #957 ), its application and methods - However this was out of scope for this PR.

This PR also compacts Vector3.new(0, 0, 0) to vector.zero where appropriate.

Please note that I understand that vector hasn't been properly announced yet and so this PR may need to sit for a little bit.

Checks

By submitting your pull request for review, you agree to the following:

• This contribution was created in whole or in part by me, and I have the right to submit it under the terms of this repository's open source licenses.
• I understand and agree that this contribution and a record of it are public, maintained indefinitely, and may be redistributed under the terms of this repository's open source licenses.
• To the best of my knowledge, all proposed changes are accurate.

[Ramdoys]

I do wonder if this would be merged or not (in its current state). Yes, the vector library is much more performant, it is also not complete yet from what I understand. This also creates an abstraction between Vector3 and Vector2, which may be confusing to new learners. I wonder if there would be a way to continue referencing Vector3, Vector2, in addition to vector that would avoid confusion. I say this due to the fact that Vector3 and Vector2 are still going to be data types (for obvious reasons), and I believe that Vector2 support will also becoming to the vector library. This actually could be pretty good, since it means Vector3 and Vector2 can act as data types for the two vectors, and then the vector library is used to deal with them. So maybe this whole confusion claim is kind of arbitrary, but I still thought it was good to mention. (Edit; This will probably not happen anytime soon, vector will be limited to Vector3.)

Nonetheless, I would like to point out that you wrote vector.**new** which would be invalid. Instead, use vector.create, the correct way to create a vector with the library. There's also situations that you haven't changed, like, Vector3:Dot, Vector3:Cross etc., though minor.

[CadeusTheGreat]

My bad on the vector.new point, thanks for poiting that out. I'll commit a fix for that now. Was just quickly replacing Vector3 for vector haha! The extra functions of the vector library I was going to do in a later PR since I was aiming for the low hanging fruit but I can take a look at those too.

[CadeusTheGreat]

PR #957 has been created by someone else to help with the migration. May update these pages to reference the new vector page instead of Vector3.

[IgnisRBX]

Hi @CadeusTheGreat ,
I just merged #957 to get the vector library documented. For now, though, let's not adjust the other code samples that use the traditional constructor(s) until the dev community gets more familiar with the newer library. Thanks!

[CadeusTheGreat]

Hi @IgnisRBX

I'll keep this branch updated and ready for the future migration. I'll change the Vector3 docs references to the vector library page linked in #957 for when you feel Roblox is ready to migrate to the new library.

I'm just curious on how long that could be as users are unlikely to migrate to the new vector library when all the documentation still references Vector3. Do you have a possible timeline on this change so I know how long I'm looking to maintain this branch for?

Thanks!

[CadeusTheGreat]

Also to be ready for the future, do you want all type references changes from Vector3 to vector? Reference pages such as Attachment, BasePart etc... have lots of references to Vector3 types which I believe could be moved to vector typing.

[IgnisRBX]

Hi again @CadeusTheGreat,
The newer library is documented!
https://create.roblox.com/docs/en-us/reference/engine/libraries/vector

In terms of replacing the call references, we're going to keep Vector3 around as the default data type for 3D vector operations. This new vector library is open for anybody's use, but Vector3 still has constructors like FromNormalId() and FromAxis() which the newer vector library doesn't (unsure if it will ever have those). I'll add a note to the Vector3 documentation page that mentions the alternative vector library, but otherwise we're planning to offer it as just an alternative and not the default. Hopefully this makes sense, and we appreciate your contributions as always!

[CadeusTheGreat]

Hi @IgnisRBX

Thanks for getting back to me, is it worth me updating the Vector3 type references to Vector3 | vector since it could be either as the vector library types as vector instead of Vector3?

Also given the increased performance of the new vector library I'd imagine it would have been preferred over the existing Vector3 API.

[github-actions]

This pull request has been inactive for 14 days. If it remains inactive for another 7 days, it will close. Please update or comment on this pull request to keep it open. 🙏

[Ramdoys]

Keep open.

[aetter]

Hi @IgnisRBX

Thanks for getting back to me, is it worth me updating the Vector3 type references to Vector3 | vector since it could be either as the vector library types as vector instead of Vector3?

Also given the increased performance of the new vector library I'd imagine it would have been preferred over the existing Vector3 API.

Hi Cadeus, union types are one of those things that I'd prefer developers use carefully and explicitly rather than grabbing them from sample code since type systems are meant to catch errors and enhance clarity. As the library gets greater adoption (and maybe some extra functions), we're always open to reconsidering how we present the data type vs. the library, but we're pretty happy with the framing of it as an alternative rather than a new default.

[github-actions]

This pull request has been inactive for 14 days. If it remains inactive for another 7 days, it will close. Please update or comment on this pull request to keep it open. 🙏

[CadeusTheGreat]

Considering closing this for now until the Luau typing and vector library are more mature. Are you able to advise (staff) if you'd prefer this closed for now & I'll revisit down the line in the future please?

[aetter]

Considering closing this for now until the Luau typing and vector library are more mature. Are you able to advise (staff) if you'd prefer this closed for now & I'll revisit down the line in the future please?

Hey Cadeus, yeah, let's close for now. Really appreciate the PR and surrounding discussion -- good food for thought on our end.