FreeCameraKeyboardWalkInput example/docs not flanging with the actual BabylonJS API?

richardtallent · June 25, 2021, 4:00pm

Hi! I’m referring to this doc and this playground (which don’t match, but are close):

I’m trying to adapt these to a TypeScript class so I can tweak the logic and use it in my code – basically, I want arrow keys to “look” without “moving” the camera. I’m using the latest 5.0 releases in my app.

I’ve run into a few problems I’m hoping someone can shed light on:

Registering/Unregistering top root events

The docs use this:

BABYLON.Tools.RegisterTopRootEvents(canvas, ...)
BABYLON.Tools.UnregisterTopRootEvents(canvas, ...)

However, there is no “canvas” in scope here. The playground example doesn’t even call RegisterTopRootEvents, but does call UnregisterTopRootEvents, and when it does so, does not provide a first argument. However, this doesn’t match the functions, which need a Window as the first argument:

github.com/BabylonJS/Babylon.js

src/Misc/tools.ts

5e6321d88


      
                  }

              }

              return true;

          }

          

          /**

           * Function used to register events at window level

           * @param windowElement defines the Window object to use

           * @param events defines the events to register

           */

          public static RegisterTopRootEvents(windowElement: Window, events: { name: string; handler: Nullable<(e: FocusEvent) => any> }[]): void {

              for (var index = 0; index < events.length; index++) {

                  var event = events[index];

                  windowElement.addEventListener(event.name, <any>event.handler, false);

          

                  try {

                      if (window.parent) {

                          window.parent.addEventListener(event.name, <any>event.handler, false);

                      }

                  } catch (e) {

                      // Silently fails...

github.com/BabylonJS/Babylon.js

src/Misc/tools.ts

5e6321d88


      
                      // Silently fails...

                  }

              }

          }

          

          /**

           * Function used to unregister events from window level

           * @param windowElement defines the Window object to use

           * @param events defines the events to unregister

           */

          public static UnregisterTopRootEvents(windowElement: Window, events: { name: string; handler: Nullable<(e: FocusEvent) => any> }[]): void {

              for (var index = 0; index < events.length; index++) {

                  var event = events[index];

                  windowElement.removeEventListener(event.name, <any>event.handler);

          

                  try {

                      if (windowElement.parent) {

                          windowElement.parent.removeEventListener(event.name, <any>event.handler);

                      }

                  } catch (e) {

                      // Silently fails...

Should I use camera.getScene().getEngine().getHostWindow() for that, as shown here?

github.com/BabylonJS/Babylon.js

src/Cameras/Inputs/BaseCameraPointersInput.ts

5e6321d88


      
              this._onLostFocus = () => {
                  this.pointA = this.pointB = null;
                  previousPinchSquaredDistance = 0;
                  previousMultiTouchPanPosition = null;
                  this.onLostFocus();
              };
          
              element && element.addEventListener("contextmenu",
                  <EventListener>this.onContextMenu.bind(this), false);
          
              let hostWindow = this.camera.getScene().getEngine().getHostWindow();
          
              if (hostWindow) {
                  Tools.RegisterTopRootEvents(hostWindow, [
                      { name: "blur", handler: this._onLostFocus }
                  ]);
              }
          }
          
          /**
           * Detach the current controls from the specified dom element.

The purpose of `_onLostFocus()`?

The documentation also doesn’t actually show an implementation of _onLostFocus(), but the playground example has one, it just sets this._keys = [];. Is that the appropriate logic? Seems reasonable based on what I think it is doing there.

TCamera doesn’t match its use in `CheckInputs()`

According to the docs, our custom input manager should implement ICameraInput, defined here:

https://github.com/BabylonJS/Babylon.js/blob/preview/src/Cameras/cameraInputsManager.ts

However, in the documentation’s implementation:

It accesses camera.cameraRotation, which doesn’t exist on Camera, but it is defined on TargetCamera. Not a big deal, just needs to be cast differently.
It says attachControl and detachControl have a parameter element: HTMLElement, but they don’t, according to the API docs (Babylon.js docs) and source code (https://github.com/BabylonJS/Babylon.js/blob/preview/src/Cameras/cameraInputsManager.ts#L35)

If I’m interpreting all of this correctly, I’m happy to put a PR in to update the documentation – assuming the docs are even meant to align with the master or current Babylon 5 alpha? There is, unfortunately, no indication on the documentation pages or API docs about which version they are targeting.

sebavan · June 25, 2021, 5:18pm

Actually all you found makes sense and we would greatly appreciate a PR to fix it !!!

The doc is always matching latest preview

Thanks a ton @richardtallent

JohnK · June 25, 2021, 7:07pm

Not sure that this is true. I thought the API section of the docs was generated from the comments in the source code of the current version (now 4.2) rather than the preview (now 5). The other sections of the docs were written at various times and could be several years old.

However, since Babylon.js has a very rigid - No Breaking Changes- policy the docs should accurately reflect the current version. In the extremely rare occasions of a breaking change occuring in the preview version this should be reflected in the current main body of the docs by the time the preview version becomes the current version. This is also true of of new features in the preview version.

Having said all that, historic errors in the docs can continue from version to version. It could be that a page of the main body of the docs was written during the development of a feature in a preview, published and not updated as the feature was tweaked before preview became current. Other ways of creating doc errors are available.

Deltakosh · June 28, 2021, 3:07pm

API is built from the current version (I hope so actually, so checking with @RaananW )

RaananW · June 28, 2021, 3:10pm

Yes, this is true. The docs are based on the latest nightly (the last one when the doc page was built, which is roughly 2 days ago)

Topic		Replies	Views
BabylonJS Documentation's example error Bugs documentation	7	587	October 25, 2019
Confusion about how to implement ICameraInput in TypeScript Questions	6	1332	March 15, 2022
CameraInputManager support for FollowCamera Questions	26	2697	February 7, 2019
Input Manager to rule them all Feature requests	41	5961	March 6, 2024
Moving the camera with the keyboard BEFORE any mouse interaction (4.2.0) Questions	9	973	July 28, 2021

FreeCameraKeyboardWalkInput example/docs not flanging with the actual BabylonJS API?

Registering/Unregistering top root events

The purpose of _onLostFocus()?

TCamera doesn’t match its use in CheckInputs()

Related topics

The purpose of `_onLostFocus()`?

TCamera doesn’t match its use in `CheckInputs()`