Skip to content

this.bga.display3D

The Display3D class provides a 3D view for one or more HTML elements. It can rotate and move the view, zoom in and out, and optionally let players control the view with the mouse.

Initialize a 3D view

this.bga.display3D.init3d(settings?: Display3DInitSettings): void;

Initializes the 3D view. If elements is not specified, the view uses the default game area elements.

The optional settings object can contain:

  • elements: an array of HTMLElement objects transformed by the 3D view.
  • showControls: whether to display the legacy 3D controls. The default is false.
  • view: the initial view and optional limits. See View settings.
  • draggable: enables dragging. It can be a boolean, a shared numeric multiplier, or a settings object.
  • zoomByWheel: enables zooming with the mouse wheel. It can be a boolean, a numeric multiplier, or a settings object.

Example:

    this.bga.display3D.init3d({
        elements: [document.getElementById("game_play_area")],
        showControls: true,
        view: {
            xAxis: 40,
            zAxis: 0,
            xPos: -100,
            yPos: -50,
            zoom: 1,
            minZoom: 0.5,
            maxZoom: 3,
        },
        draggable: true,
        zoomByWheel: true,
    });

Elements

this.bga.display3D.setElements(elements: HTMLElement[]): void;

Replaces the list of elements transformed by the 3D view.

this.bga.display3D.addElements(elements: HTMLElement[]): void;

Add elements to the list of elements transformed by the 3D view.

Changing the view

this.bga.display3D.change3d(xaxis: number, xpos: number, ypos: number, zaxis: number, scale: number): void;

Applies relative changes to the current view. The arguments are, in order, X-axis rotation, X-position, Y-position, Z-axis rotation, and zoom changes.

this.bga.display3D.resetView(): void;

Resets the view to its neutral position while respecting the configured limits.

this.bga.display3D.rotate(x: number, y: number): void;

Applies a relative rotation. x changes the X-axis rotation and y changes the Z-axis rotation.

this.bga.display3D.slide(x: number, y: number): void;

Applies a relative translation. x changes the X position and y changes the Y position.

this.bga.display3D.zoom(inc: number): void;

Applies a relative zoom change.

this.bga.display3D.setZoom(value: number): void;

Sets the zoom to an absolute value.

Example:

    this.bga.display3D.rotate(5, 0);
    this.bga.display3D.slide(10, -5);
    this.bga.display3D.zoom(0.1);
    this.bga.display3D.setZoom(1);

Mouse controls

this.bga.display3D.setDraggable(enabled?: boolean | number | Display3DDraggableSettings, settings?: number | Display3DDraggableSettings): void;

Enables or disables mouse dragging. Right-button dragging rotates the view and middle-button dragging slides the view.

The first argument can be a boolean, a shared multiplier, or an object with these properties:

  • enabled: whether dragging is enabled. The default is true when using the object form.
  • multiplier: shared rotation and slide multiplier.
  • rotationMultiplier: right-button rotation multiplier. The default is 0.1.
  • slideMultiplier: middle-button slide multiplier. The default is 1.

The second argument can provide the settings object or a shared numeric multiplier.

Examples:

    this.bga.display3D.setDraggable(true);
    this.bga.display3D.setDraggable(false);
    this.bga.display3D.setDraggable({
        rotationMultiplier: 0.1,
        slideMultiplier: 1,
    });

this.bga.display3D.setZoomByWheel(enabled?: boolean | number | Display3DZoomByWheelSettings, settings?: number | Display3DZoomByWheelSettings): void;

Enables or disables mouse-wheel zooming.

The first argument can be a boolean, a zoom multiplier, or an object with these properties:

  • enabled: whether wheel zoom is enabled. The default is true when using the object form.
  • multiplier: wheel zoom multiplier. The default is 0.1.
  • zoomMultiplier: alias for multiplier, also defaulting to 0.1.

The second argument can provide the settings object or a numeric multiplier.

Example:

    this.bga.display3D.setZoomByWheel({
        multiplier: 0.1,
    });

View settings

The view object passed to init3d can set the initial view and its limits. All properties are optional:

  • xAxis, minXAxis, maxXAxis: X-axis rotation and its limits.
  • zAxis, minZAxis, maxZAxis: Z-axis rotation and its limits.
  • xPos, minXPos, maxXPos: X position and its limits.
  • yPos, minYPos, maxYPos: Y position and its limits.
  • zoom, minZoom, maxZoom: zoom and its limits.

Changing view limits

Each limit method sets one limit. Passing null clears that limit.

this.bga.display3D.setMinXAxis(value?: number | null): void;

this.bga.display3D.setMaxXAxis(value?: number | null): void;

this.bga.display3D.setMinZAxis(value?: number | null): void;

this.bga.display3D.setMaxZAxis(value?: number | null): void;

this.bga.display3D.setMinXPos(value?: number | null): void;

this.bga.display3D.setMaxXPos(value?: number | null): void;

this.bga.display3D.setMinYPos(value?: number | null): void;

this.bga.display3D.setMaxYPos(value?: number | null): void;

this.bga.display3D.setMinZoom(value?: number | null): void;

this.bga.display3D.setMaxZoom(value?: number | null): void;

Example:

    this.bga.display3D.setMinZoom(0.5);
    this.bga.display3D.setMaxZoom(3);
    this.bga.display3D.setMaxZoom(null); // Remove the maximum zoom limit