Example Playgrounds for Properties and Methods of Vector3

[BabylonJSGuide]

My apologies for the length of this comment, it is because I need advice on whether it will be part of my very limited project or a much larger undertaking by the community. As a large community undertaking it needs considering and approval by @deltakosh along with @PirateJC and @RaananW as it involves the docs even though it is on the API side and I would like to include @sebavan as he as also been very supportive and helpful to me. Please include anyone else you would like to talk to about it.

Reason Behind PR
Within the API classes the search the playground for each property and method is at best hit and miss, so I thought that each property and method of a class should have its own playground example, which should be simple and as meaningful as possible. For my limited project, except for a few where they were trivial or I couldn't think of a good example or I forgot, I have done this for all the methods and classes of Vector3 in this PR.

Implications for a Large Community Undertaking
An announcement about the undertaking.
If members do put in example PGs they could come in piecemeal so lots of individual PRs, unless there was somewhere else to submit them. This would require a moderator or moderators.
Some rules for submitting an example PG, eg

1. PGs should be simple and where possible meaningful.
2. Code for the particular property or method should appear near the top of the PG
   When meaningful means more complex code this can be achieved by wrapping the
   a. method code in a function as in https://playground.babylonjs.com/#R1F8YU#111
   b. method code within an onBeforeRenderObservable as in https://playground.babylonjs.com/#R1F8YU#63
   c. complex code within functions as in https://playground.babylonjs.com/#R1F8YU#106
3. There should be comments at the top describing the method/property also stating the example use matching a template
4. Template PGs for each class would be needed
5. New or edited methods without a PG should have a PG submitted when method PR submitted

I am sure there are more implications and I am happy for the rules to change. I only came up with them after doing half the methods.

Also as members of the community have their own agendas it is probably wishful thinking that enough people would get involved to get it done.

In terms of my very limited project I am happy to continue with the math.vector.ts classes, eg Vector2, Vector4, etc

Let me know what you think and whether it is just my limited project or a community appeal.

[azure-pipelines]

Please make sure to label your PR with "bug", "new feature" or "breaking change" label(s).
To prevent this PR from going to the changelog marked it with the "skip changelog" label.

[azure-pipelines]

Snapshot stored with reference name:
refs/pull/12874/merge

Test environment:
https://babylonsnapshots.z22.web.core.windows.net/refs/pull/12874/merge/index.html

To test a playground add it to the URL, for example:

https://babylonsnapshots.z22.web.core.windows.net/refs/pull/12874/merge/index.html#WGZLGJ#4600

Links to test babylon tools with this snapshot:

https://playground.babylonjs.com/?snapshot=refs/pull/12874/merge
https://sandbox.babylonjs.com/?snapshot=refs/pull/12874/merge
https://gui.babylonjs.com/?snapshot=refs/pull/12874/merge
https://nme.babylonjs.com/?snapshot=refs/pull/12874/merge

To test the snapshot in the playground with a playground ID add it after the snapshot query string:

https://playground.babylonjs.com/?snapshot=refs/pull/12874/merge#BCU1XR#0

[RaananW]

Wow, thank you so much John! This is amazing.
I didn't go into all of the examples, but a playground to each of those methods will be very very helpful. especially for functions like project/unproject which can sometimes be a mystery.

There is a very small formatting issue and I think it will be great if the example be a part of the description (i.e. - before the @returns and @param lines.

[BabylonJSGuide]

Wow, thank you so much John! This is amazing. I didn't go into all of the examples, but a playground to each of those methods will be very very helpful. especially for functions like project/unproject which can sometimes be a mystery.

There is a very small formatting issue and I think it will be great if the example be a part of the description (i.e. - before the @returns and @param lines.

Having problems getting prettier to run to correct any formatting errors.

Also tried
npm run format:check and got

PS C:\Users\johnk\Documents\Github\Babylon.js> npm run format:check

@babylonjs/root@1.0.0 format:check
prettier --check ./packages//src//*.{ts,tsx,js,json,scss,css}

'prettier' is not recognized as an internal or external command,
operable program or batch file.

I have checked that is it set as default formatter for all languages.

Just found the format error (I hope) exactly one extra space at the end of one line.

Happy to move it before @params and @return.

Will wait until any more suggestions so I can deal with them in one go.

[RaananW]

Wow, thank you so much John! This is amazing. I didn't go into all of the examples, but a playground to each of those methods will be very very helpful. especially for functions like project/unproject which can sometimes be a mystery.
There is a very small formatting issue and I think it will be great if the example be a part of the description (i.e. - before the @returns and @param lines.

Having problems getting prettier to run to correct any formatting errors.

Also tried npm run format:check and got

PS C:\Users\johnk\Documents\Github\Babylon.js> npm run format:check

@babylonjs/root@1.0.0 format:check
prettier --check ./packages//src//*.{ts,tsx,js,json,scss,css}

'prettier' is not recognized as an internal or external command, operable program or batch file.

I have checked that is it set as default formatter for all languages.

Just found the format error (I hope) exactly one extra space at the end of one line.

Happy to move it before @params and @return.

Will wait until any more suggestions so I can deal with them in one go.

Hey @BabylonJSGuide, so sorry about that prettier issue.
can you try running npm install prettier and try running the formatter right after? If that doesn't work, try installing prettier globally (i.e. npm install prettier -g). And as a final solution, try this -
npx prettier --write ./packages/**/src/**/*.{ts,tsx,js,json,scss,css}

If that doesn't work let's hop on a call to check what's up with your local repo.

[BabylonJSGuide]

Hi @RaananW, thank you for the help. It was my problem, I just did a new clone of Babylon.js and then behaved as if it was the old one. Completely forgot to do npm install. All well now. As no more suggestions will get on with move Example line to descriptions.

[BabylonJSGuide]

Examples move up to descriptions as requested

[azure-pipelines]

Please make sure to label your PR with "bug", "new feature" or "breaking change" label(s).
To prevent this PR from going to the changelog marked it with the "skip changelog" label.

[azure-pipelines]

Snapshot stored with reference name:
refs/pull/12874/merge

Test environment:
https://babylonsnapshots.z22.web.core.windows.net/refs/pull/12874/merge/index.html

To test a playground add it to the URL, for example:

https://babylonsnapshots.z22.web.core.windows.net/refs/pull/12874/merge/index.html#WGZLGJ#4600

Links to test babylon tools with this snapshot:

https://playground.babylonjs.com/?snapshot=refs/pull/12874/merge
https://sandbox.babylonjs.com/?snapshot=refs/pull/12874/merge
https://gui.babylonjs.com/?snapshot=refs/pull/12874/merge
https://nme.babylonjs.com/?snapshot=refs/pull/12874/merge

To test the snapshot in the playground with a playground ID add it after the snapshot query string:

https://playground.babylonjs.com/?snapshot=refs/pull/12874/merge#BCU1XR#0