@playcanvas/web-components 0.10.1 → 0.11.0

package/dist/app.d.ts

@@ -1,5 +1,6 @@
-import { AppBase } from 'playcanvas';
+import { AppBase, Entity } from 'playcanvas';
 import { AsyncElement } from './async-element';
+import { EntityElement } from './entity';
 /**
  * The AppElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
@@ -19,12 +20,24 @@ declare class AppElement extends AsyncElement {
     private _alpha;
     private _backend;
     private _antialias;
-    private _depth;
-    private _stencil;
-    private _highResolution;
+    private _depthBuffer;
+    private _stencilBuffer;
+    private _maxPixelRatio;
     private _loadingBar;
+    /**
+     * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+     * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+     * cleared on disconnect so a re-connected element boots from its current attributes.
+     */
+    private _optionsLocked;
     private _bar;
     private _hierarchyReady;
+    /**
+     * The elements backing this application's entities, keyed by the entity itself. Registered
+     * by EntityElement at creation and removed when an entity is destroyed, this joins engine
+     * scene nodes back to their owning elements by identity - never by name.
+     */
+    private _entityElements;
     private _picker;
     private _hasPointerListeners;
     private _hoveredEntity;
@@ -58,6 +71,50 @@ declare class AppElement extends AsyncElement {
     _onWindowResize(): void;
     _pickerCreate(): void;
     _pickerDestroy(): void;
+    /**
+     * Registers the element that created an entity. Called by EntityElement when it creates its
+     * entity.
+     *
+     * @param entity - The entity.
+     * @param element - The element that created it.
+     * @ignore
+     */
+    _registerEntityElement(entity: Entity, element: EntityElement): void;
+    /**
+     * Removes the registration for a destroyed entity. Called by EntityElement.
+     *
+     * @param entity - The entity.
+     * @ignore
+     */
+    _unregisterEntityElement(entity: Entity): void;
+    /**
+     * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
+     * entity was not created by an element of this application - for example, a node inside a
+     * model's instantiated hierarchy, or an entity created through the engine API.
+     *
+     * @param entity - The entity to look up.
+     * @returns The element backing the entity, or `null`.
+     */
+    elementFromEntity(entity: Entity): EntityElement | null;
+    /**
+     * Resolves the element that owns a picked node: the nearest node up the parent chain -
+     * starting with the node itself - that was created by a `<pc-entity>` of this application.
+     * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
+     * the model.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The owning element, or `null`.
+     */
+    private _elementFromNode;
+    /**
+     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
+     * on an unlistened child still reaches a listening ancestor.
+     *
+     * @param node - The picked node, or `null`.
+     * @param type - The pointer event type a listener is required for.
+     * @returns The nearest listening element, or `null`.
+     */
+    private _elementWithListener;
     private _getPickerCoordinates;
     /**
      * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
@@ -77,28 +134,37 @@ declare class AppElement extends AsyncElement {
     _onPointerListenerAdded(type: string): void;
     _onPointerListenerRemoved(type: string): void;
     /**
-     * Sets the alpha flag.
+     * Warns that a graphics option was written too late to have any effect. These options are read
+     * once, when the element connects and creates its graphics device, so a later write updates
+     * only the element's own property - silently, without this.
+     *
+     * @param name - The name of the option, as its attribute.
+     */
+    private _warnIfBooted;
+    /**
+     * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+     * wherever the scene has not drawn. Read only when the application boots.
      * @param value - The alpha flag.
      */
     set alpha(value: boolean);
     /**
-     * Gets the alpha flag.
+     * Gets whether the frame buffer has an alpha channel.
      * @returns The alpha flag.
      */
     get alpha(): boolean;
     /**
-     * Sets the antialias flag.
+     * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
      * @param value - The antialias flag.
      */
     set antialias(value: boolean);
     /**
-     * Gets the antialias flag.
+     * Gets whether the frame buffer is anti-aliased.
      * @returns The antialias flag.
      */
     get antialias(): boolean;
     /**
      * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
-     * is not supported by the browser.
+     * is not supported by the browser. Read only when the application boots.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null');
@@ -108,32 +174,22 @@ declare class AppElement extends AsyncElement {
      */
     get backend(): "webgpu" | "webgl2" | "null";
     /**
-     * Sets the depth flag.
-     * @param value - The depth flag.
+     * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+     * surface is nearest the camera. Read only when the application boots.
+     * @param value - The depth buffer flag.
      */
-    set depth(value: boolean);
+    set depthBuffer(value: boolean);
     /**
-     * Gets the depth flag.
-     * @returns The depth flag.
+     * Gets whether the frame buffer has a depth buffer.
+     * @returns The depth buffer flag.
      */
-    get depth(): boolean;
+    get depthBuffer(): boolean;
     /**
      * Gets the hierarchy ready flag.
      * @returns The hierarchy ready flag.
      * @ignore
      */
     get hierarchyReady(): boolean;
-    /**
-     * Sets the high resolution flag. When true, the application will render at the device's
-     * physical resolution. When false, the application will render at CSS resolution.
-     * @param value - The high resolution flag.
-     */
-    set highResolution(value: boolean);
-    /**
-     * Gets the high resolution flag.
-     * @returns The high resolution flag.
-     */
-    get highResolution(): boolean;
     /**
      * Sets whether the application shows its built-in loading bar while it boots and preloads its
      * assets. Enabled by default; setting `false` removes the bar immediately, while setting
@@ -150,15 +206,30 @@ declare class AppElement extends AsyncElement {
      */
     get loadingBar(): boolean;
     /**
-     * Sets the stencil flag.
-     * @param value - The stencil flag.
+     * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+     * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+     * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+     * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+     * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+     * @param value - The maximum pixel ratio.
+     */
+    set maxPixelRatio(value: number);
+    /**
+     * Gets the cap on the pixel ratio the application renders at.
+     * @returns The maximum pixel ratio.
+     */
+    get maxPixelRatio(): number;
+    /**
+     * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+     * masking need. Read only when the application boots.
+     * @param value - The stencil buffer flag.
      */
-    set stencil(value: boolean);
+    set stencilBuffer(value: boolean);
     /**
-     * Gets the stencil flag.
-     * @returns The stencil flag.
+     * Gets whether the frame buffer has a stencil buffer.
+     * @returns The stencil buffer flag.
      */
-    get stencil(): boolean;
+    get stencilBuffer(): boolean;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }

package/dist/components/camera-component.d.ts

@@ -21,7 +21,7 @@ declare class CameraComponentElement extends ComponentElement {
     private _gamma;
     private _horizontalFov;
     private _nearClip;
-    private _orthographic;
+    private _projection;
     private _orthoHeight;
     private _priority;
     private _rect;
@@ -42,12 +42,12 @@ declare class CameraComponentElement extends ComponentElement {
         gammaCorrection: 0 | 1;
         horizontalFov: boolean;
         nearClip: number;
-        projection: 0 | 1;
+        projection: number;
         orthoHeight: number;
         priority: number;
         rect: Vec4;
         scissorRect: Vec4;
-        toneMapping: number | undefined;
+        toneMapping: number;
     };
     get xrAvailable(): boolean | null;
     /**
@@ -186,16 +186,6 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The near clip distance.
      */
     get nearClip(): number;
-    /**
-     * Sets the orthographic projection of the camera.
-     * @param value - The orthographic projection.
-     */
-    set orthographic(value: boolean);
-    /**
-     * Gets the orthographic projection of the camera.
-     * @returns The orthographic projection.
-     */
-    get orthographic(): boolean;
     /**
      * Sets the orthographic height of the camera.
      * @param value - The orthographic height.
@@ -216,6 +206,16 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The priority.
      */
     get priority(): number;
+    /**
+     * Sets the projection of the camera. Use `orthoHeight` to size an orthographic projection.
+     * @param value - The projection ('perspective' or 'orthographic').
+     */
+    set projection(value: 'perspective' | 'orthographic');
+    /**
+     * Gets the projection of the camera.
+     * @returns The projection.
+     */
+    get projection(): "perspective" | "orthographic";
     /**
      * Sets the rect of the camera.
      * @param value - The rect.

package/dist/components/screen-component.d.ts

@@ -13,7 +13,7 @@ declare class ScreenComponentElement extends ComponentElement {
     private _resolution;
     private _referenceResolution;
     private _priority;
-    private _blend;
+    private _scaleMode;
     private _scaleBlend;
     /** @ignore */
     constructor();
@@ -22,7 +22,7 @@ declare class ScreenComponentElement extends ComponentElement {
         referenceResolution: Vec2;
         resolution: Vec2;
         scaleBlend: number;
-        scaleMode: "none" | "blend";
+        scaleMode: string;
         screenSpace: boolean;
     };
     /**
@@ -36,10 +36,31 @@ declare class ScreenComponentElement extends ComponentElement {
     get referenceResolution(): Vec2;
     set resolution(value: Vec2);
     get resolution(): Vec2;
+    /**
+     * Sets how the screen's `resolution` and `referenceResolution` are weighted against each other
+     * when `scaleMode` is `blend`, from 0 (follow the resolution) to 1 (follow the reference
+     * resolution). Ignored while `scaleMode` is `none`.
+     * @param value - The scale blend factor.
+     */
     set scaleBlend(value: number);
+    /**
+     * Gets how the screen's resolutions are weighted against each other.
+     * @returns The scale blend factor.
+     */
     get scaleBlend(): number;
-    set blend(value: boolean);
-    get blend(): boolean;
+    /**
+     * Sets how the screen scales its contents. `none` renders at `resolution` and ignores
+     * `referenceResolution`; `blend` scales between the two, weighted by `scaleBlend`, which is what
+     * keeps a UI laid out at one resolution usable at another. Requires `screenSpace` - the engine
+     * forces `none` on a world-space screen, which does not support scaling.
+     * @param value - The scale mode ('none' or 'blend').
+     */
+    set scaleMode(value: 'none' | 'blend');
+    /**
+     * Gets how the screen scales its contents.
+     * @returns The scale mode.
+     */
+    get scaleMode(): "none" | "blend";
     set screenSpace(value: boolean);
     get screenSpace(): boolean;
     static get observedAttributes(): string[];

package/dist/components/scrollview-component.d.ts

@@ -31,22 +31,24 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get component(): ScrollViewComponent;
     /**
-     * Sets whether horizontal scrolling is enabled.
+     * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
      * @param value - Whether horizontal scrolling is enabled.
      */
     set horizontal(value: boolean);
     /**
-     * Gets whether horizontal scrolling is enabled.
+     * Gets whether scrolling along the horizontal axis is enabled.
      * @returns Whether horizontal scrolling is enabled.
      */
     get horizontal(): boolean;
     /**
-     * Sets whether vertical scrolling is enabled.
+     * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
      * @param value - Whether vertical scrolling is enabled.
      */
     set vertical(value: boolean);
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical(): boolean;