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):

https://playground.babylonjs.com/#CTCSWQ#1

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/blob/5e6321d887637877d8b28b417410abbbeb651c6e/src/Misc/tools.ts#L551

    
      
                  }

              }

              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/blob/5e6321d887637877d8b28b417410abbbeb651c6e/src/Misc/tools.ts#L571

    
      
                      // 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/blob/5e6321d887637877d8b28b417410abbbeb651c6e/src/Cameras/Inputs/BaseCameraPointersInput.ts#L234

    
      
              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:

github.com

BabylonJS/Babylon.js/blob/preview/src/Cameras/cameraInputsManager.ts

import { Logger } from "../Misc/logger";
import { SerializationHelper } from "../Misc/decorators";
import { Nullable } from "../types";
import { Camera } from "./camera";
/**
 * @ignore
 * This is a list of all the different input types that are available in the application.
 * Fo instance: ArcRotateCameraGamepadInput...
 */
export var CameraInputTypes = {};

/**
 * This is the contract to implement in order to create a new input class.
 * Inputs are dealing with listening to user actions and moving the camera accordingly.
 */
export interface ICameraInput<TCamera extends Camera> {
    /**
     * Defines the camera the input is attached to.
     */
    camera: Nullable<TCamera>;

This file has been truncated. show original

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 (ICameraInput | Babylon.js Documentation) and source code (Babylon.js/cameraInputsManager.ts at preview · BabylonJS/Babylon.js · GitHub)

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	564	October 25, 2019
Customising camera doesn't seem to work for me Questions documentation , tutorial	4	671	July 16, 2020
Confusion about how to implement ICameraInput in TypeScript Questions	6	1309	March 15, 2022
Creating a custom orthographic camera Questions camera , pointerevents , orthographic , inputmanager	11	1034	July 14, 2023
Looking for the keyboard control method for UniversalCamera Questions	4	452	June 18, 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()`