From 93da7ca4277b09243ffdeada04425dd99b21bd59 Mon Sep 17 00:00:00 2001 From: Martin Valigursky Date: Wed, 12 Jun 2024 11:27:35 +0100 Subject: [PATCH] Cherry picked: Add JSDoc for getters (#6685) --- src/core/math/curve-set.js | 9 +- src/core/shape/oriented-box.js | 7 +- src/extras/gizmo/gizmo.js | 14 +- src/extras/gizmo/rotate-gizmo.js | 35 +- src/extras/gizmo/scale-gizmo.js | 70 ++- src/extras/gizmo/transform-gizmo.js | 35 +- src/extras/gizmo/translate-gizmo.js | 56 +- src/extras/mini-stats/mini-stats.js | 32 +- src/framework/anim/evaluator/anim-track.js | 7 +- src/framework/app-base.js | 8 +- src/framework/asset/asset-list-loader.js | 2 +- src/framework/asset/asset-reference.js | 14 +- src/framework/asset/asset.js | 56 +- .../components/anim/component-layer.js | 44 +- src/framework/components/anim/component.js | 37 +- .../components/animation/component.js | 32 +- src/framework/components/button/component.js | 119 +++- src/framework/components/camera/component.js | 256 ++++++-- .../components/collision/component.js | 128 +++- src/framework/components/component.js | 7 +- src/framework/components/element/component.js | 567 +++++++++++++----- src/framework/components/gsplat/component.js | 37 +- .../components/layout-child/component.js | 51 +- .../components/layout-group/component.js | 67 ++- src/framework/components/light/component.js | 363 ++++++++--- src/framework/components/model/component.js | 127 +++- .../components/particle-system/component.js | 537 ++++++++++++++--- src/framework/components/render/component.js | 118 +++- .../components/rigid-body/component.js | 167 ++++-- src/framework/components/screen/component.js | 60 +- src/framework/components/script/component.js | 9 +- .../components/scroll-view/component.js | 127 +++- .../components/scrollbar/component.js | 39 +- src/framework/components/sound/component.js | 72 ++- src/framework/components/sound/slot.js | 72 ++- src/framework/components/sound/system.js | 9 +- src/framework/components/sprite/component.js | 123 +++- .../sprite/sprite-animation-clip.js | 34 +- src/framework/handlers/handler.js | 7 +- src/framework/i18n/i18n.js | 20 +- src/framework/script/script-type.js | 15 +- src/framework/utils/entity-reference.js | 2 +- src/framework/xr/xr-dom-overlay.js | 9 +- src/framework/xr/xr-input-source.js | 7 +- src/framework/xr/xr-tracked-image.js | 5 + src/platform/graphics/blend-state.js | 9 +- src/platform/graphics/depth-state.js | 50 +- src/platform/graphics/graphics-device.js | 20 +- src/platform/graphics/render-target.js | 4 +- src/platform/graphics/stencil-parameters.js | 53 +- src/platform/graphics/texture.js | 70 ++- .../graphics/webgl/webgl-graphics-device.js | 12 +- .../graphics/webgpu/webgpu-graphics-device.js | 4 +- .../webgpu/webgpu-vertex-buffer-layout.js | 2 +- src/platform/input/game-pads.js | 16 +- src/platform/sound/instance.js | 59 +- src/platform/sound/instance3d.js | 46 +- src/platform/sound/manager.js | 9 +- src/scene/animation/skeleton.js | 18 +- src/scene/graph-node.js | 195 +++--- src/scene/layer.js | 32 +- src/scene/lighting/lighting-params.js | 62 +- src/scene/materials/material.js | 137 ++++- src/scene/mesh-instance.js | 81 ++- src/scene/mesh.js | 15 +- src/scene/morph-target.js | 4 +- src/scene/morph.js | 2 +- src/scene/scene.js | 131 +++- src/scene/sprite.js | 28 +- src/scene/texture-atlas.js | 14 +- tsconfig.json | 23 - 71 files changed, 3670 insertions(+), 1038 deletions(-) diff --git a/src/core/math/curve-set.js b/src/core/math/curve-set.js index b06095f095a..29a5f2702e8 100644 --- a/src/core/math/curve-set.js +++ b/src/core/math/curve-set.js @@ -61,7 +61,7 @@ class CurveSet { } /** - * The number of curves in the curve set. + * Gets the number of curves in the curve set. * * @type {number} */ @@ -70,7 +70,7 @@ class CurveSet { } /** - * The interpolation scheme applied to all curves in the curve set. Can be: + * Sets the interpolation scheme applied to all curves in the curve set. Can be: * * - {@link CURVE_LINEAR} * - {@link CURVE_SMOOTHSTEP} @@ -88,6 +88,11 @@ class CurveSet { } } + /** + * Gets the interpolation scheme applied to all curves in the curve set. + * + * @type {number} + */ get type() { return this._type; } diff --git a/src/core/shape/oriented-box.js b/src/core/shape/oriented-box.js index dc04c81a058..94627d0eb7f 100644 --- a/src/core/shape/oriented-box.js +++ b/src/core/shape/oriented-box.js @@ -57,7 +57,7 @@ class OrientedBox { } /** - * The world transform of the OBB. + * Sets the world transform of the OBB. * * @type {Mat4} */ @@ -66,6 +66,11 @@ class OrientedBox { this._modelTransform.copy(value).invert(); } + /** + * Gets the world transform of the OBB. + * + * @type {Mat4} + */ get worldTransform() { return this._worldTransform; } diff --git a/src/extras/gizmo/gizmo.js b/src/extras/gizmo/gizmo.js index d4abb4512e2..aa4aa306699 100644 --- a/src/extras/gizmo/gizmo.js +++ b/src/extras/gizmo/gizmo.js @@ -299,7 +299,7 @@ class Gizmo extends EventHandler { } /** - * The gizmo coordinate space. Can be: + * Sets the gizmo coordinate space. Can be: * * - {@link GIZMO_LOCAL} * - {@link GIZMO_WORLD} @@ -313,12 +313,17 @@ class Gizmo extends EventHandler { this._updateRotation(); } + /** + * Gets the gizmo coordinate space. + * + * @type {string} + */ get coordSpace() { return this._coordSpace; } /** - * The gizmo size. Defaults to 1. + * Sets the gizmo size. Defaults to 1. * * @type {number} */ @@ -327,6 +332,11 @@ class Gizmo extends EventHandler { this._updateScale(); } + /** + * Gets the gizmo size. + * + * @type {number} + */ get size() { return this._size; } diff --git a/src/extras/gizmo/rotate-gizmo.js b/src/extras/gizmo/rotate-gizmo.js index e4184a14b4e..e43a98f9217 100644 --- a/src/extras/gizmo/rotate-gizmo.js +++ b/src/extras/gizmo/rotate-gizmo.js @@ -174,7 +174,7 @@ class RotateGizmo extends TransformGizmo { } /** - * XYZ tube radius. + * Sets the XYZ tube radius. * * @type {number} */ @@ -182,12 +182,17 @@ class RotateGizmo extends TransformGizmo { this._setDiskProp('tubeRadius', value); } + /** + * Gets the XYZ tube radius. + * + * @type {number} + */ get xyzTubeRadius() { return this._shapes.x.tubeRadius; } /** - * XYZ ring radius. + * Sets the XYZ ring radius. * * @type {number} */ @@ -195,12 +200,17 @@ class RotateGizmo extends TransformGizmo { this._setDiskProp('ringRadius', value); } + /** + * Gets the XYZ ring radius. + * + * @type {number} + */ get xyzRingRadius() { return this._shapes.x.ringRadius; } /** - * Face tube radius. + * Sets the face tube radius. * * @type {number} */ @@ -208,12 +218,17 @@ class RotateGizmo extends TransformGizmo { this._shapes.face.tubeRadius = value; } + /** + * Gets the face tube radius. + * + * @type {number} + */ get faceTubeRadius() { return this._shapes.face.tubeRadius; } /** - * Face ring radius. + * Sets the face ring radius. * * @type {number} */ @@ -221,12 +236,17 @@ class RotateGizmo extends TransformGizmo { this._shapes.face.ringRadius = value; } + /** + * Gets the face ring radius. + * + * @type {number} + */ get faceRingRadius() { return this._shapes.face.ringRadius; } /** - * Ring tolerance. + * Sets the ring tolerance. * * @type {number} */ @@ -235,6 +255,11 @@ class RotateGizmo extends TransformGizmo { this._shapes.face.tolerance = value; } + /** + * Gets the ring tolerance. + * + * @type {number} + */ get ringTolerance() { return this._shapes.x.tolerance; } diff --git a/src/extras/gizmo/scale-gizmo.js b/src/extras/gizmo/scale-gizmo.js index d6a153fa571..05e606e6e9e 100644 --- a/src/extras/gizmo/scale-gizmo.js +++ b/src/extras/gizmo/scale-gizmo.js @@ -136,7 +136,7 @@ class ScaleGizmo extends TransformGizmo { } /** - * Uniform scaling state for planes. + * Sets the uniform scaling state for planes. * * @type {boolean} */ @@ -144,12 +144,17 @@ class ScaleGizmo extends TransformGizmo { this._useUniformScaling = value ?? true; } + /** + * Gets the uniform scaling state for planes. + * + * @type {boolean} + */ get uniform() { return this._useUniformScaling; } /** - * Axis gap. + * Sets the axis gap. * * @type {number} */ @@ -157,12 +162,17 @@ class ScaleGizmo extends TransformGizmo { this._setArrowProp('gap', value); } + /** + * Gets the axis gap. + * + * @type {number} + */ get axisGap() { return this._shapes.x.gap; } /** - * Axis line thickness. + * Sets the axis line thickness. * * @type {number} */ @@ -170,12 +180,17 @@ class ScaleGizmo extends TransformGizmo { this._setArrowProp('lineThickness', value); } + /** + * Gets the axis line thickness. + * + * @type {number} + */ get axisLineThickness() { return this._shapes.x.lineThickness; } /** - * Axis line length. + * Sets the axis line length. * * @type {number} */ @@ -183,12 +198,17 @@ class ScaleGizmo extends TransformGizmo { this._setArrowProp('lineLength', value); } + /** + * Gets the axis line length. + * + * @type {number} + */ get axisLineLength() { return this._shapes.x.lineLength; } /** - * Axis line tolerance. + * Sets the axis line tolerance. * * @type {number} */ @@ -196,12 +216,17 @@ class ScaleGizmo extends TransformGizmo { this._setArrowProp('tolerance', value); } + /** + * Gets the axis line tolerance. + * + * @type {number} + */ get axisLineTolerance() { return this._shapes.x.tolerance; } /** - * Axis box size. + * Sets the axis box size. * * @type {number} */ @@ -209,12 +234,17 @@ class ScaleGizmo extends TransformGizmo { this._setArrowProp('boxSize', value); } + /** + * Gets the axis box size. + * + * @type {number} + */ get axisBoxSize() { return this._shapes.x.boxSize; } /** - * Plane size. + * Sets the plane size. * * @type {number} */ @@ -222,12 +252,17 @@ class ScaleGizmo extends TransformGizmo { this._setPlaneProp('size', value); } + /** + * Gets the plane size. + * + * @type {number} + */ get axisPlaneSize() { return this._shapes.yz.size; } /** - * Plane gap. + * Sets the plane gap. * * @type {number} */ @@ -235,12 +270,17 @@ class ScaleGizmo extends TransformGizmo { this._setPlaneProp('gap', value); } + /** + * Gets the plane gap. + * + * @type {number} + */ get axisPlaneGap() { return this._shapes.yz.gap; } /** - * Axis center size. + * Sets the axis center size. * * @type {number} */ @@ -248,12 +288,17 @@ class ScaleGizmo extends TransformGizmo { this._shapes.xyz.size = value; } + /** + * Gets the axis center size. + * + * @type {number} + */ get axisCenterSize() { return this._shapes.xyz.size; } /** - * Axis center tolerance. + * Sets the axis center tolerance. * * @type {number} */ @@ -261,6 +306,11 @@ class ScaleGizmo extends TransformGizmo { this._shapes.xyz.tolerance = value; } + /** + * Gets the axis center tolerance. + * + * @type {number} + */ get axisCenterTolerance() { return this._shapes.xyz.tolerance; } diff --git a/src/extras/gizmo/transform-gizmo.js b/src/extras/gizmo/transform-gizmo.js index fea4c1d4be9..3e1029de981 100644 --- a/src/extras/gizmo/transform-gizmo.js +++ b/src/extras/gizmo/transform-gizmo.js @@ -371,7 +371,7 @@ class TransformGizmo extends Gizmo { } /** - * State for if snapping is enabled. Defaults to false. + * Sets whether snapping is enabled. Defaults to false. * * @type {boolean} */ @@ -379,12 +379,17 @@ class TransformGizmo extends Gizmo { this._snap = this.root.enabled && value; } + /** + * Gets whether snapping is enabled. Defaults to false. + * + * @type {boolean} + */ get snap() { return this._snap; } /** - * X axis color. + * Sets the X axis color. * * @type {Color} */ @@ -392,12 +397,17 @@ class TransformGizmo extends Gizmo { this._updateAxisColor('x', value); } + /** + * Gets the X axis color. + * + * @type {Color} + */ get xAxisColor() { return this._meshColors.axis.x; } /** - * Y axis color. + * Sets the Y axis color. * * @type {Color} */ @@ -405,12 +415,17 @@ class TransformGizmo extends Gizmo { this._updateAxisColor('y', value); } + /** + * Gets the Y axis color. + * + * @type {Color} + */ get yAxisColor() { return this._meshColors.axis.y; } /** - * Z axis color. + * Sets the Z axis color. * * @type {Color} */ @@ -418,12 +433,17 @@ class TransformGizmo extends Gizmo { this._updateAxisColor('z', value); } + /** + * Gets the Z axis color. + * + * @type {Color} + */ get zAxisColor() { return this._meshColors.axis.z; } /** - * The color alpha for all axes. + * Sets the color alpha for all axes. * * @type {number} */ @@ -441,6 +461,11 @@ class TransformGizmo extends Gizmo { } } + /** + * Gets the color alpha for all axes. + * + * @type {number} + */ get colorAlpha() { return this._colorAlpha; } diff --git a/src/extras/gizmo/translate-gizmo.js b/src/extras/gizmo/translate-gizmo.js index 28b7bc34577..398df482fba 100644 --- a/src/extras/gizmo/translate-gizmo.js +++ b/src/extras/gizmo/translate-gizmo.js @@ -120,7 +120,7 @@ class TranslateGizmo extends TransformGizmo { } /** - * Axis gap. + * Sets the axis gap. * * @type {number} */ @@ -128,12 +128,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('gap', value); } + /** + * Gets the axis gap. + * + * @type {number} + */ get axisGap() { return this._shapes.x.gap; } /** - * Axis line thickness. + * Sets the axis line thickness. * * @type {number} */ @@ -141,12 +146,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('lineThickness', value); } + /** + * Gets the axis line thickness. + * + * @type {number} + */ get axisLineThickness() { return this._shapes.x.lineThickness; } /** - * Axis line length. + * Sets the axis line length. * * @type {number} */ @@ -154,12 +164,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('lineLength', value); } + /** + * Gets the axis line length. + * + * @type {number} + */ get axisLineLength() { return this._shapes.x.lineLength; } /** - * Axis line tolerance. + * Sets the axis line tolerance. * * @type {number} */ @@ -167,12 +182,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('tolerance', value); } + /** + * Gets the axis line tolerance. + * + * @type {number} + */ get axisLineTolerance() { return this._shapes.x.tolerance; } /** - * Arrow thickness. + * Sets the arrow thickness. * * @type {number} */ @@ -180,12 +200,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('arrowThickness', value); } + /** + * Gets the arrow thickness. + * + * @type {number} + */ get axisArrowThickness() { return this._shapes.x.arrowThickness; } /** - * Arrow length. + * Sets the arrow length. * * @type {number} */ @@ -193,12 +218,17 @@ class TranslateGizmo extends TransformGizmo { this._setArrowProp('arrowLength', value); } + /** + * Gets the arrow length. + * + * @type {number} + */ get axisArrowLength() { return this._shapes.x.arrowLength; } /** - * Plane size. + * Sets the plane size. * * @type {number} */ @@ -206,12 +236,17 @@ class TranslateGizmo extends TransformGizmo { this._setPlaneProp('size', value); } + /** + * Gets the plane size. + * + * @type {number} + */ get axisPlaneSize() { return this._shapes.yz.size; } /** - * Plane gap. + * Sets the plane gap. * * @type {number} */ @@ -219,6 +254,11 @@ class TranslateGizmo extends TransformGizmo { this._setPlaneProp('gap', value); } + /** + * Gets the plane gap. + * + * @type {number} + */ get axisPlaneGap() { return this._shapes.yz.gap; } diff --git a/src/extras/mini-stats/mini-stats.js b/src/extras/mini-stats/mini-stats.js index 5102c8167b3..0c10ff559c0 100644 --- a/src/extras/mini-stats/mini-stats.js +++ b/src/extras/mini-stats/mini-stats.js @@ -199,9 +199,10 @@ class MiniStats { } /** - * Get/set the active size index. Setting the active size index will resize the overlay to the + * Sets the active size index. Setting the active size index will resize the overlay to the * size specified by the corresponding entry in the sizes array. * + * @type {number} * @ignore */ set activeSizeIndex(value) { @@ -210,28 +211,40 @@ class MiniStats { this.resize(this.sizes[value].width, this.sizes[value].height, this.sizes[value].graphs); } - /** @ignore */ + /** + * Gets the active size index. + * + * @type {number} + * @ignore + */ get activeSizeIndex() { return this._activeSizeIndex; } /** - * Get/set the opacity of the MiniStats overlay. + * Sets the opacity of the MiniStats overlay. * + * @type {number} * @ignore */ set opacity(value) { this.clr[3] = value; } - /** @ignore */ + /** + * Gets the opacity of the MiniStats overlay. + * + * @type {number} + * @ignore + */ get opacity() { return this.clr[3]; } /** - * Get the overall height of the MiniStats overlay. + * Gets the overall height of the MiniStats overlay. * + * @type {number} * @ignore */ get overallHeight() { @@ -241,7 +254,9 @@ class MiniStats { } /** - * Get/set the enabled state of the MiniStats overlay. + * Sets the enabled state of the MiniStats overlay. + * + * @type {boolean} */ set enabled(value) { if (value !== this._enabled) { @@ -253,6 +268,11 @@ class MiniStats { } } + /** + * Gets the enabled state of the MiniStats overlay. + * + * @type {boolean} + */ get enabled() { return this._enabled; } diff --git a/src/framework/anim/evaluator/anim-track.js b/src/framework/anim/evaluator/anim-track.js index 56f8cf64b35..c48c8dec28f 100644 --- a/src/framework/anim/evaluator/anim-track.js +++ b/src/framework/anim/evaluator/anim-track.js @@ -82,7 +82,7 @@ class AnimTrack { /** - * The animation events that will fire during the playback of this anim track. + * Sets the animation events that will fire during the playback of this anim track. * * @type {AnimEvents} */ @@ -90,6 +90,11 @@ class AnimTrack { this._animEvents = animEvents; } + /** + * Gets the animation events that will fire during the playback of this anim track. + * + * @type {AnimEvents} + */ get events() { return this._animEvents.events; } diff --git a/src/framework/app-base.js b/src/framework/app-base.js index cec23c42367..bbf7e64e73c 100644 --- a/src/framework/app-base.js +++ b/src/framework/app-base.js @@ -1531,7 +1531,7 @@ class AppBase extends EventHandler { * - {@link SHADOW_PCF3}: PCF 3x3 sampling. * - {@link SHADOW_PCF5}: PCF 5x5 sampling. Falls back to {@link SHADOW_PCF3} on WebGL 1.0. * - * @param {Vec3} settings.render.lightingCells - Number of cells along each world-space axis the space containing lights + * @param {Vec3} settings.render.lightingCells - Number of cells along each world space axis the space containing lights * is subdivided into. * * Only lights with bakeDir=true will be used for generating the dominant light direction. @@ -1664,11 +1664,11 @@ class AppBase extends EventHandler { } /** - * Draws a single line. Line start and end coordinates are specified in world-space. The line + * Draws a single line. Line start and end coordinates are specified in world space. The line * will be flat-shaded with the specified color. * - * @param {Vec3} start - The start world-space coordinate of the line. - * @param {Vec3} end - The end world-space coordinate of the line. + * @param {Vec3} start - The start world space coordinate of the line. + * @param {Vec3} end - The end world space coordinate of the line. * @param {Color} [color] - The color of the line. It defaults to white if not specified. * @param {boolean} [depthTest] - Specifies if the line is depth tested against the depth * buffer. Defaults to true. diff --git a/src/framework/asset/asset-list-loader.js b/src/framework/asset/asset-list-loader.js index ae97d20c80f..0822e688e59 100644 --- a/src/framework/asset/asset-list-loader.js +++ b/src/framework/asset/asset-list-loader.js @@ -32,7 +32,7 @@ class AssetListLoader extends EventHandler { * const assetListLoader = new pc.AssetListLoader([ * new pc.Asset("texture1", "texture", { url: 'http://example.com/my/assets/here/texture1.png') }), * new pc.Asset("texture2", "texture", { url: 'http://example.com/my/assets/here/texture2.png') }) - * ], pc.app.assets); + * ], app.assets); */ constructor(assetList, assetRegistry) { super(); diff --git a/src/framework/asset/asset-reference.js b/src/framework/asset/asset-reference.js index 056e4dd9c7c..d792b6b1917 100644 --- a/src/framework/asset/asset-reference.js +++ b/src/framework/asset/asset-reference.js @@ -53,7 +53,7 @@ class AssetReference { } /** - * Get or set the asset id which this references. One of either id or url must be set to + * Sets the asset id which this references. One of either id or url must be set to * initialize an asset reference. * * @type {number} @@ -69,12 +69,17 @@ class AssetReference { this._bind(); } + /** + * Gets the asset id which this references. + * + * @type {number} + */ get id() { return this._id; } /** - * Get or set the asset url which this references. One of either id or url must be called to + * Sets the asset url which this references. One of either id or url must be called to * initialize an asset reference. * * @type {string|null} @@ -90,6 +95,11 @@ class AssetReference { this._bind(); } + /** + * Gets the asset url which this references. + * + * @type {string|null} + */ get url() { return this._url; } diff --git a/src/framework/asset/asset.js b/src/framework/asset/asset.js index d6e413f1cd4..45c14d0a919 100644 --- a/src/framework/asset/asset.js +++ b/src/framework/asset/asset.js @@ -228,7 +228,7 @@ class Asset extends EventHandler { } /** - * The asset id. + * Sets the asset id. * * @type {number} */ @@ -236,12 +236,17 @@ class Asset extends EventHandler { this._id = value; } + /** + * Gets the asset id. + * + * @type {number} + */ get id() { return this._id; } /** - * The asset name. + * Sets the asset name. * * @type {string} */ @@ -253,12 +258,17 @@ class Asset extends EventHandler { this.fire('name', this, this._name, old); } + /** + * Gets the asset name. + * + * @type {string} + */ get name() { return this._name; } /** - * The file details or null if no file. + * Sets the file details or null if no file. * * @type {object} */ @@ -302,14 +312,19 @@ class Asset extends EventHandler { } } + /** + * Gets the file details or null if no file. + * + * @type {object} + */ get file() { return this._file; } /** - * Optional JSON data that contains either the complete resource data. (e.g. in the case of a - * material) or additional data (e.g. in the case of a model it contains mappings from mesh to - * material). + * Sets optional asset JSON data. This contains either the complete resource data (such as in + * the case of a material) or additional data (such as in the case of a model which contains + * mappings from mesh to material). * * @type {object} */ @@ -326,12 +341,17 @@ class Asset extends EventHandler { } } + /** + * Gets optional asset JSON data. + * + * @type {object} + */ get data() { return this._data; } /** - * A reference to the resource when the asset is loaded. e.g. a {@link Texture} or a {@link Model}. + * Sets the asset resource. For example, a {@link Texture} or a {@link Model}. * * @type {object} */ @@ -341,13 +361,18 @@ class Asset extends EventHandler { this.fire('change', this, 'resource', value, _old); } + /** + * Gets the asset resource. + * + * @type {object} + */ get resource() { return this._resources[0]; } /** - * A reference to the resources of the asset when it's loaded. An asset can hold more runtime - * resources than one e.g. cubemaps. + * Sets the asset resources. Some assets can hold more than one runtime resource (cube maps, + * for example). * * @type {object[]} */ @@ -357,12 +382,18 @@ class Asset extends EventHandler { this.fire('change', this, 'resources', value, _old); } + /** + * Gets the asset resources. + * + * @type {object[]} + */ get resources() { return this._resources; } /** - * If true the asset will be loaded during the preload phase of application set up. + * Sets whether to preload an asset. If true, the asset will be loaded during the preload phase + * of application set up. * * @type {boolean} */ @@ -376,6 +407,11 @@ class Asset extends EventHandler { this.registry.load(this); } + /** + * Gets whether to preload an asset. + * + * @type {boolean} + */ get preload() { return this._preload; } diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index d9162a032f3..bb232e3c274 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -86,7 +86,7 @@ class AnimComponentLayer { } /** - * Whether this layer is currently playing. + * Sets whether this layer is currently playing. * * @type {boolean} */ @@ -94,6 +94,11 @@ class AnimComponentLayer { this._controller.playing = value; } + /** + * Gets whether this layer is currently playing. + * + * @type {boolean} + */ get playing() { return this._controller.playing; } @@ -109,7 +114,7 @@ class AnimComponentLayer { } /** - * Returns the currently active state name. + * Gets the currently active state name. * * @type {string} */ @@ -118,7 +123,7 @@ class AnimComponentLayer { } /** - * Returns the previously active state name. + * Gets the previously active state name. * * @type {string|null} */ @@ -127,7 +132,7 @@ class AnimComponentLayer { } /** - * Returns the currently active state's progress as a value normalized by the state's animation + * Gets the currently active state's progress as a value normalized by the state's animation * duration. Looped animations will return values greater than 1. * * @type {number} @@ -137,7 +142,7 @@ class AnimComponentLayer { } /** - * Returns the currently active states duration. + * Gets the currently active states duration. * * @type {number} */ @@ -146,7 +151,7 @@ class AnimComponentLayer { } /** - * The active states time in seconds. + * Sets the active state's time in seconds. * * @type {number} */ @@ -161,12 +166,17 @@ class AnimComponentLayer { controller.playing = layerPlaying; } + /** + * Gets the active state's time in seconds. + * + * @type {number} + */ get activeStateCurrentTime() { return this._controller.activeStateCurrentTime; } /** - * Returns whether the anim component layer is currently transitioning between states. + * Gets whether the anim component layer is currently transitioning between states. * * @type {boolean} */ @@ -175,7 +185,7 @@ class AnimComponentLayer { } /** - * If the anim component layer is currently transitioning between states, returns the progress. + * Gets the progress, if the anim component layer is currently transitioning between states. * Otherwise returns null. * * @type {number|null} @@ -188,7 +198,7 @@ class AnimComponentLayer { } /** - * Lists all available states in this layers state graph. + * Gets all available states in this layers state graph. * * @type {string[]} */ @@ -197,8 +207,8 @@ class AnimComponentLayer { } /** - * The blending weight of this layer. Used when calculating the value of properties that are - * animated by more than one layer. + * Sets the blending weight of this layer. Used when calculating the value of properties that + * are animated by more than one layer. * * @type {number} */ @@ -207,6 +217,11 @@ class AnimComponentLayer { this._component.dirtifyTargets(); } + /** + * Sets the blending weight of this layer. + * + * @type {number} + */ get weight() { return this._weight; } @@ -225,7 +240,7 @@ class AnimComponentLayer { } /** - * A mask of bones which should be animated or ignored by this layer. + * Sets the mask of bones which should be animated or ignored by this layer. * * @type {object} * @example @@ -245,6 +260,11 @@ class AnimComponentLayer { this._mask = value; } + /** + * Gets the mask of bones which should be animated or ignored by this layer. + * + * @type {object} + */ get mask() { return this._mask; } diff --git a/src/framework/components/anim/component.js b/src/framework/components/anim/component.js index 9262364d4da..38dd2e14d19 100644 --- a/src/framework/components/anim/component.js +++ b/src/framework/components/anim/component.js @@ -98,7 +98,7 @@ class AnimComponent extends Component { /** - * If true the animation component will normalize the weights of its layers by their sum total. + * Sets whether the animation component will normalize the weights of its layers by their sum total. * * @type {boolean} */ @@ -107,6 +107,11 @@ class AnimComponent extends Component { this.unbind(); } + /** + * Gets whether the animation component will normalize the weights of its layers by their sum total. + * + * @type {boolean} + */ get normalizeWeights() { return this._normalizeWeights; } @@ -121,7 +126,7 @@ class AnimComponent extends Component { } /** - * Speed multiplier for animation play back speed. 1.0 is playback at normal speed, 0.0 pauses + * Sets the speed multiplier for animation play back speed. 1.0 is playback at normal speed, 0.0 pauses * the animation. * * @type {number} @@ -130,12 +135,17 @@ class AnimComponent extends Component { this._speed = value; } + /** + * Gets the speed multiplier for animation play back speed. + * + * @type {number} + */ get speed() { return this._speed; } /** - * If true the first animation will begin playing when the scene is loaded. + * Sets whether the first animation will begin playing when the scene is loaded. * * @type {boolean} */ @@ -143,13 +153,18 @@ class AnimComponent extends Component { this._activate = value; } + /** + * Gets whether the first animation will begin playing when the scene is loaded. + * + * @type {boolean} + */ get activate() { return this._activate; } /** - * Plays or pauses all animations in the component. + * Sets whether to play or pause all animations in the component. * * @type {boolean} */ @@ -157,12 +172,17 @@ class AnimComponent extends Component { this._playing = value; } + /** + * Gets whether to play or pause all animations in the component. + * + * @type {boolean} + */ get playing() { return this._playing; } /** - * The entity that this anim component should use as the root of the animation hierarchy. + * Sets the entity that this anim component should use as the root of the animation hierarchy. * * @type {Entity} */ @@ -179,6 +199,11 @@ class AnimComponent extends Component { this.rebind(); } + /** + * Gets the entity that this anim component should use as the root of the animation hierarchy. + * + * @type {Entity} + */ get rootBone() { return this._rootBone; } @@ -548,7 +573,7 @@ class AnimComponent extends Component { * animation should be associated with. Each section of a blend tree path is split using a * period (`.`) therefore state names should not include this character (e.g "MyStateName" or * "MyStateName.BlendTreeNode"). - * @param {object} animTrack - The animation track that will be assigned to this state and + * @param {AnimTrack} animTrack - The animation track that will be assigned to this state and * played whenever this state is active. * @param {string} [layerName] - The name of the anim component layer to update. If omitted the * default layer is used. If no state graph has been previously loaded this parameter is diff --git a/src/framework/components/animation/component.js b/src/framework/components/animation/component.js index 6b7bd30e2d0..a1c843aed50 100644 --- a/src/framework/components/animation/component.js +++ b/src/framework/components/animation/component.js @@ -92,7 +92,7 @@ class AnimationComponent extends Component { blendSpeed = 0; /** - * If true the first animation asset will begin playing when the scene is loaded. + * If true, the first animation asset will begin playing when the scene is loaded. * * @type {boolean} */ @@ -119,7 +119,7 @@ class AnimationComponent extends Component { } /** - * Get or set dictionary of animations by name. + * Sets the dictionary of animations by name. * * @type {Object} */ @@ -129,12 +129,17 @@ class AnimationComponent extends Component { this.onSetAnimations(); } + /** + * Gets the dictionary of animations by name. + * + * @type {Object} + */ get animations() { return this._animations; } /** - * The array of animation assets. Can also be an array of asset ids. + * Sets the array of animation assets or asset ids. * * @type {Array.} */ @@ -171,12 +176,17 @@ class AnimationComponent extends Component { this.loadAnimationAssets(assetIds); } + /** + * Gets the array of animation assets or asset ids. + * + * @type {Array.} + */ get assets() { return this._assets; } /** - * Get or set the current time position (in seconds) of the animation. + * Sets the current time position (in seconds) of the animation. * * @type {number} */ @@ -195,6 +205,11 @@ class AnimationComponent extends Component { } } + /** + * Gets the current time position (in seconds) of the animation. + * + * @type {number} + */ get currentTime() { if (this.skeleton) { return this.skeleton._time; @@ -213,7 +228,7 @@ class AnimationComponent extends Component { } /** - * Get the duration in seconds of the current animation. Returns 0 if no animation is playing. + * Gets the duration in seconds of the current animation. Returns 0 if no animation is playing. * * @type {number} */ @@ -227,7 +242,7 @@ class AnimationComponent extends Component { } /** - * If true the animation will restart from the beginning when it reaches the end. + * Sets whether the animation will restart from the beginning when it reaches the end. * * @type {boolean} */ @@ -245,6 +260,11 @@ class AnimationComponent extends Component { } } + /** + * Gets whether the animation will restart from the beginning when it reaches the end. + * + * @type {boolean} + */ get loop() { return this._loop; } diff --git a/src/framework/components/button/component.js b/src/framework/components/button/component.js index d82ca2f6db7..2280629a1b0 100644 --- a/src/framework/components/button/component.js +++ b/src/framework/components/button/component.js @@ -282,18 +282,26 @@ class ButtonComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { this._setValue('enabled', arg); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } /** - * If set to false, the button will be visible but will not respond to hover or touch interactions. + * Sets the button's active state. If set to false, the button will be visible but will not + * respond to hover or touch interactions. Defaults to true. * * @type {boolean} */ @@ -301,13 +309,18 @@ class ButtonComponent extends Component { this._setValue('active', arg); } + /** + * Gets the button's active state. + * + * @type {boolean} + */ get active() { return this.data.active; } /** - * A reference to the entity to be used as the button background. The entity must have an - * ImageElement component. + * Sets the entity to be used as the button background. The entity must have an + * {@link ElementComponent} configured as an image element. * * @type {import('../../../framework/entity.js').Entity} */ @@ -315,13 +328,18 @@ class ButtonComponent extends Component { this._setValue('imageEntity', arg); } + /** + * Gets the entity to be used as the button background. + * + * @type {import('../../../framework/entity.js').Entity} + */ get imageEntity() { return this.data.imageEntity; } /** - * Padding to be used in hit-test calculations. Can be used to expand the bounding box so that - * the button is easier to tap. + * Sets the padding to be used in hit-test calculations. Can be used to expand the bounding box + * so that the button is easier to tap. Defaults to `[0, 0, 0, 0]`. * * @type {import('../../../core/math/vec4.js').Vec4} */ @@ -329,12 +347,23 @@ class ButtonComponent extends Component { this._setValue('hitPadding', arg); } + /** + * Gets the padding to be used in hit-test calculations. + * + * @type {import('../../../core/math/vec4.js').Vec4} + */ get hitPadding() { return this.data.hitPadding; } /** - * Controls how the button responds when the user hovers over it/presses it. + * Sets the button transition mode. This controls how the button responds when the user hovers + * over it/presses it. Can be: + * + * - {@link BUTTON_TRANSITION_MODE_TINT} + * - {@link BUTTON_TRANSITION_MODE_SPRITE_CHANGE} + * + * Defaults to {@link BUTTON_TRANSITION_MODE_TINT}. * * @type {number} */ @@ -342,12 +371,18 @@ class ButtonComponent extends Component { this._setValue('transitionMode', arg); } + /** + * Gets the button transition mode. + * + * @type {number} + */ get transitionMode() { return this.data.transitionMode; } /** - * Color to be used on the button image when the user hovers over it. + * Sets the tint color to be used on the button image when the user hovers over it. Defaults to + * `[0.75, 0.75, 0.75]`. * * @type {Color} */ @@ -355,12 +390,18 @@ class ButtonComponent extends Component { this._setValue('hoverTint', arg); } + /** + * Gets the tint color to be used on the button image when the user hovers over it. + * + * @type {Color} + */ get hoverTint() { return this.data.hoverTint; } /** - * Color to be used on the button image when the user presses it. + * Sets the tint color to be used on the button image when the user presses it. Defaults to + * `[0.5, 0.5, 0.5]`. * * @type {Color} */ @@ -368,12 +409,18 @@ class ButtonComponent extends Component { this._setValue('pressedTint', arg); } + /** + * Gets the tint color to be used on the button image when the user presses it. + * + * @type {Color} + */ get pressedTint() { return this.data.pressedTint; } /** - * Color to be used on the button image when the button is not interactive. + * Sets the tint color to be used on the button image when the button is not interactive. + * Defaults to `[0.25, 0.25, 0.25]`. * * @type {Color} */ @@ -381,12 +428,17 @@ class ButtonComponent extends Component { this._setValue('inactiveTint', arg); } + /** + * Gets the tint color to be used on the button image when the button is not interactive. + * + * @type {Color} + */ get inactiveTint() { return this.data.inactiveTint; } /** - * Duration to be used when fading between tints, in milliseconds. + * Sets the duration to be used when fading between tints, in milliseconds. Defaults to 0. * * @type {number} */ @@ -394,12 +446,17 @@ class ButtonComponent extends Component { this._setValue('fadeDuration', arg); } + /** + * Gets the duration to be used when fading between tints, in milliseconds. + * + * @type {number} + */ get fadeDuration() { return this.data.fadeDuration; } /** - * Sprite to be used as the button image when the user hovers over it. + * Sets the sprite to be used as the button image when the user hovers over it. * * @type {import('../../../framework/asset/asset.js').Asset} */ @@ -407,12 +464,17 @@ class ButtonComponent extends Component { this._setValue('hoverSpriteAsset', arg); } + /** + * Gets the sprite to be used as the button image when the user hovers over it. + * + * @type {import('../../../framework/asset/asset.js').Asset} + */ get hoverSpriteAsset() { return this.data.hoverSpriteAsset; } /** - * Frame to be used from the hover sprite. + * Sets the frame to be used from the hover sprite. * * @type {number} */ @@ -420,12 +482,17 @@ class ButtonComponent extends Component { this._setValue('hoverSpriteFrame', arg); } + /** + * Gets the frame to be used from the hover sprite. + * + * @type {number} + */ get hoverSpriteFrame() { return this.data.hoverSpriteFrame; } /** - * Sprite to be used as the button image when the user presses it. + * Sets the sprite to be used as the button image when the user presses it. * * @type {import('../../../framework/asset/asset.js').Asset} */ @@ -433,12 +500,17 @@ class ButtonComponent extends Component { this._setValue('pressedSpriteAsset', arg); } + /** + * Gets the sprite to be used as the button image when the user presses it. + * + * @type {import('../../../framework/asset/asset.js').Asset} + */ get pressedSpriteAsset() { return this.data.pressedSpriteAsset; } /** - * Frame to be used from the pressed sprite. + * Sets the frame to be used from the pressed sprite. * * @type {number} */ @@ -446,12 +518,17 @@ class ButtonComponent extends Component { this._setValue('pressedSpriteFrame', arg); } + /** + * Gets the frame to be used from the pressed sprite. + * + * @type {number} + */ get pressedSpriteFrame() { return this.data.pressedSpriteFrame; } /** - * Sprite to be used as the button image when the button is not interactive. + * Sets the sprite to be used as the button image when the button is not interactive. * * @type {import('../../../framework/asset/asset.js').Asset} */ @@ -459,12 +536,17 @@ class ButtonComponent extends Component { this._setValue('inactiveSpriteAsset', arg); } + /** + * Gets the sprite to be used as the button image when the button is not interactive. + * + * @type {import('../../../framework/asset/asset.js').Asset} + */ get inactiveSpriteAsset() { return this.data.inactiveSpriteAsset; } /** - * Frame to be used from the inactive sprite. + * Sets the frame to be used from the inactive sprite. * * @type {number} */ @@ -472,6 +554,11 @@ class ButtonComponent extends Component { this._setValue('inactiveSpriteFrame', arg); } + /** + * Gets the frame to be used from the inactive sprite. + * + * @type {number} + */ get inactiveSpriteFrame() { return this.data.inactiveSpriteFrame; } diff --git a/src/framework/components/camera/component.js b/src/framework/components/camera/component.js index a1f7d68e4f8..b904878b47a 100644 --- a/src/framework/components/camera/component.js +++ b/src/framework/components/camera/component.js @@ -179,7 +179,7 @@ class CameraComponent extends Component { } /** - * Sets the render passes the camera will use for rendering, instead of its default rendering. + * Sets the render passes the camera uses for rendering, instead of its default rendering. * Set this to an empty array to return to the default behavior. * * @type {import('../../../platform/graphics/render-pass.js').RenderPass[]} @@ -189,12 +189,18 @@ class CameraComponent extends Component { this._camera.renderPasses = passes; } + /** + * Gets the render passes the camera uses for rendering, instead of its default rendering. + * + * @type {import('../../../platform/graphics/render-pass.js').RenderPass[]} + * @ignore + */ get renderPasses() { return this._camera.renderPasses; } /** - * Set camera aperture in f-stops, the default value is 16.0. Higher value means less exposure. + * Sets the camera aperture in f-stops. Default is 16. Higher value means less exposure. * * @type {number} */ @@ -202,12 +208,17 @@ class CameraComponent extends Component { this._camera.aperture = value; } + /** + * Gets the camera aperture in f-stops. + * + * @type {number} + */ get aperture() { return this._camera.aperture; } /** - * The aspect ratio (width divided by height) of the camera. If aspectRatioMode is + * Sets the aspect ratio (width divided by height) of the camera. If `aspectRatioMode` is * {@link ASPECT_AUTO}, then this value will be automatically calculated every frame, and you * can only read it. If it's ASPECT_MANUAL, you can set the value. * @@ -217,12 +228,17 @@ class CameraComponent extends Component { this._camera.aspectRatio = value; } + /** + * Gets the aspect ratio (width divided by height) of the camera. + * + * @type {number} + */ get aspectRatio() { return this._camera.aspectRatio; } /** - * The aspect ratio mode of the camera. Can be: + * Sets the aspect ratio mode of the camera. Can be: * * - {@link ASPECT_AUTO}: aspect ratio will be calculated from the current render * target's width divided by height. @@ -236,14 +252,20 @@ class CameraComponent extends Component { this._camera.aspectRatioMode = value; } + /** + * Gets the aspect ratio mode of the camera. + * + * @type {number} + */ get aspectRatioMode() { return this._camera.aspectRatioMode; } /** - * Custom function you can provide to calculate the camera projection matrix manually. Can be - * used for complex effects like doing oblique projection. Function is called using component's - * scope. Arguments: + * Sets the custom function to calculate the camera projection matrix manually. Can be used for + * complex effects like doing oblique projection. Function is called using component's scope. + * + * Arguments: * * - {@link Mat4} transformMatrix: output of the function * - view: Type of view. Can be {@link VIEW_CENTER}, {@link VIEW_LEFT} or {@link VIEW_RIGHT}. @@ -256,14 +278,18 @@ class CameraComponent extends Component { this._camera.calculateProjection = value; } + /** + * Gets the custom function to calculate the camera projection matrix manually. + * + * @type {CalculateMatrixCallback} + */ get calculateProjection() { return this._camera.calculateProjection; } /** - * Custom function you can provide to calculate the camera transformation matrix manually. Can - * be used for complex effects like reflections. Function is called using component's scope. - * Arguments: + * Sets the custom function to calculate the camera transformation matrix manually. Can be used + * for complex effects like reflections. Function is called using component's scope. Arguments: * * - {@link Mat4} transformMatrix: output of the function. * - view: Type of view. Can be {@link VIEW_CENTER}, {@link VIEW_LEFT} or {@link VIEW_RIGHT}. @@ -276,12 +302,17 @@ class CameraComponent extends Component { this._camera.calculateTransform = value; } + /** + * Gets the custom function to calculate the camera transformation matrix manually. + * + * @type {CalculateMatrixCallback} + */ get calculateTransform() { return this._camera.calculateTransform; } /** - * Queries the camera component's underlying Camera instance. + * Gets the camera component's underlying Camera instance. * * @type {Camera} * @ignore @@ -291,8 +322,7 @@ class CameraComponent extends Component { } /** - * The color used to clear the canvas to before the camera starts to render. Defaults to - * [0.75, 0.75, 0.75, 1]. + * Sets the camera component's clear color. Defaults to `[0.75, 0.75, 0.75, 1]`. * * @type {import('../../../core/math/color.js').Color} */ @@ -300,12 +330,17 @@ class CameraComponent extends Component { this._camera.clearColor = value; } + /** + * Gets the camera component's clear color. + * + * @type {import('../../../core/math/color.js').Color} + */ get clearColor() { return this._camera.clearColor; } /** - * If true the camera will clear the color buffer to the color set in clearColor. Defaults to true. + * Sets whether the camera will automatically clear the color buffer before rendering. Defaults to true. * * @type {boolean} */ @@ -314,12 +349,17 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets whether the camera will automatically clear the color buffer before rendering. + * + * @type {boolean} + */ get clearColorBuffer() { return this._camera.clearColorBuffer; } /** - * If true the camera will clear the depth buffer. Defaults to true. + * Sets whether the camera will automatically clear the depth buffer before rendering. Defaults to true. * * @type {boolean} */ @@ -328,12 +368,17 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets whether the camera will automatically clear the depth buffer before rendering. + * + * @type {boolean} + */ get clearDepthBuffer() { return this._camera.clearDepthBuffer; } /** - * If true the camera will clear the stencil buffer. Defaults to true. + * Sets whether the camera will automatically clear the stencil buffer before rendering. Defaults to true. * * @type {boolean} */ @@ -342,13 +387,19 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets whether the camera will automatically clear the stencil buffer before rendering. + * + * @type {boolean} + */ get clearStencilBuffer() { return this._camera.clearStencilBuffer; } /** - * If true the camera will take material.cull into account. Otherwise both front and back faces - * will be rendered. Defaults to true. + * Sets whether the camera will cull triangle faces. If true, the camera will take + * `material.cull` into account. Otherwise both front and back faces will be rendered. Defaults + * to true. * * @type {boolean} */ @@ -356,15 +407,20 @@ class CameraComponent extends Component { this._camera.cullFaces = value; } + /** + * Gets whether the camera will cull triangle faces. + * + * @type {boolean} + */ get cullFaces() { return this._camera.cullFaces; } /** - * Layer ID of a layer on which the postprocessing of the camera stops being applied to. - * Defaults to LAYERID_UI, which causes post processing to not be applied to UI layer and any - * following layers for the camera. Set to undefined for post-processing to be applied to all - * layers of the camera. + * Sets the layer id of the layer on which the post-processing of the camera stops being applied + * to. Defaults to {@link LAYERID_UI}, which causes post-processing to not be applied to UI + * layer and any following layers for the camera. Set to `undefined` for post-processing to be + * applied to all layers of the camera. * * @type {number} */ @@ -373,12 +429,18 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets the layer id of the layer on which the post-processing of the camera stops being applied + * to. + * + * @type {number} + */ get disablePostEffectsLayer() { return this._disablePostEffectsLayer; } /** - * The distance from the camera after which no rendering will take place. Defaults to 1000. + * Sets the distance from the camera after which no rendering will take place. Defaults to 1000. * * @type {number} */ @@ -386,13 +448,19 @@ class CameraComponent extends Component { this._camera.farClip = value; } + /** + * Gets the distance from the camera after which no rendering will take place. + * + * @type {number} + */ get farClip() { return this._camera.farClip; } /** - * If true the camera will invert front and back faces. Can be useful for reflection rendering. - * Defaults to false. + * Sets whether the camera will flip the face direction of triangles. If set to true, the + * camera will invert front and back faces. Can be useful for reflection rendering. Defaults to + * false. * * @type {boolean} */ @@ -400,14 +468,19 @@ class CameraComponent extends Component { this._camera.flipFaces = value; } + /** + * Gets whether the camera will flip the face direction of triangles. + * + * @type {boolean} + */ get flipFaces() { return this._camera.flipFaces; } /** - * The field of view of the camera in degrees. Usually this is the Y-axis field of view, see - * {@link CameraComponent#horizontalFov}. Used for {@link PROJECTION_PERSPECTIVE} cameras only. - * Defaults to 45. + * Sets the field of view of the camera in degrees. Usually this is the Y-axis field of view, + * see {@link CameraComponent#horizontalFov}. Used for {@link PROJECTION_PERSPECTIVE} cameras + * only. Defaults to 45. * * @type {number} */ @@ -415,12 +488,17 @@ class CameraComponent extends Component { this._camera.fov = value; } + /** + * Gets the field of view of the camera in degrees. + * + * @type {number} + */ get fov() { return this._camera.fov; } /** - * Queries the camera's frustum shape. + * Gets the camera's frustum shape. * * @type {import('../../../core/shape/frustum.js').Frustum} */ @@ -429,9 +507,10 @@ class CameraComponent extends Component { } /** - * Controls the culling of mesh instances against the camera frustum, i.e. if objects outside - * of camera should be omitted from rendering. If false, all mesh instances in the scene are - * rendered by the camera, regardless of visibility. Defaults to false. + * Sets whether frustum culling is enabled. This controls the culling of mesh instances against + * the camera frustum, i.e. if objects outside of the camera's frustum should be omitted from + * rendering. If false, all mesh instances in the scene are rendered by the camera, regardless + * of visibility. Defaults to false. * * @type {boolean} */ @@ -439,12 +518,18 @@ class CameraComponent extends Component { this._camera.frustumCulling = value; } + /** + * Gets whether frustum culling is enabled. + * + * @type {boolean} + */ get frustumCulling() { return this._camera.frustumCulling; } /** - * Set which axis to use for the Field of View calculation. Defaults to false. + * Sets whether the camera's field of view (`fov`) is horizontal or vertical. Defaults to + * false (meaning it is vertical be default). * * @type {boolean} */ @@ -452,14 +537,19 @@ class CameraComponent extends Component { this._camera.horizontalFov = value; } + /** + * Gets whether the camera's field of view (`fov`) is horizontal or vertical. + * + * @type {boolean} + */ get horizontalFov() { return this._camera.horizontalFov; } /** - * An array of layer IDs ({@link Layer#id}) to which this camera should belong. Don't push, - * pop, splice or modify this array, if you want to change it, set a new one instead. Defaults - * to [LAYERID_WORLD, LAYERID_DEPTH, LAYERID_SKYBOX, LAYERID_UI, LAYERID_IMMEDIATE]. + * Sets the array of layer IDs ({@link Layer#id}) to which this camera should belong. Don't + * push, pop, splice or modify this array, if you want to change it, set a new one instead. + * Defaults to `[LAYERID_WORLD, LAYERID_DEPTH, LAYERID_SKYBOX, LAYERID_UI, LAYERID_IMMEDIATE]`. * * @type {number[]} */ @@ -482,6 +572,11 @@ class CameraComponent extends Component { } } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this camera belongs. + * + * @type {number[]} + */ get layers() { return this._camera.layers; } @@ -491,9 +586,9 @@ class CameraComponent extends Component { } /** - * A jitter intensity applied in the projection matrix. Used for jittered sampling by TAA. - * A value of 1 represents a jitter in the range of [-1 to 1] of a pixel. Smaller values result - * in a crisper yet more aliased outcome, whereas increased values produce smoother but blurred + * Sets the jitter intensity applied in the projection matrix. Used for jittered sampling by TAA. + * A value of 1 represents a jitter in the range of `[-1, 1]` of a pixel. Smaller values result + * in a crisper yet more aliased outcome, whereas increased values produce a smoother but blurred * result. Defaults to 0, representing no jitter. * * @type {number} @@ -502,12 +597,17 @@ class CameraComponent extends Component { this._camera.jitter = value; } + /** + * Gets the jitter intensity applied in the projection matrix. + * + * @type {number} + */ get jitter() { return this._camera.jitter; } /** - * The distance from the camera before which no rendering will take place. Defaults to 0.1. + * Sets the distance from the camera before which no rendering will take place. Defaults to 0.1. * * @type {number} */ @@ -515,12 +615,17 @@ class CameraComponent extends Component { this._camera.nearClip = value; } + /** + * Gets the distance from the camera before which no rendering will take place. + * + * @type {number} + */ get nearClip() { return this._camera.nearClip; } /** - * The half-height of the orthographic view window (in the Y-axis). Used for + * Sets the half-height of the orthographic view window (in the Y-axis). Used for * {@link PROJECTION_ORTHOGRAPHIC} cameras only. Defaults to 10. * * @type {number} @@ -529,12 +634,18 @@ class CameraComponent extends Component { this._camera.orthoHeight = value; } + /** + * Gets the half-height of the orthographic view window (in the Y-axis). + * + * @type {number} + */ get orthoHeight() { return this._camera.orthoHeight; } /** - * The post effects queue for this camera. Use this to add or remove post effects from the camera. + * Gets the post effects queue for this camera. Use this to add or remove post effects from the + * camera. * * @type {PostEffectQueue} */ @@ -547,8 +658,8 @@ class CameraComponent extends Component { } /** - * Controls the order in which cameras are rendered. Cameras with smaller values for priority - * are rendered first. Defaults to 0. + * Sets the priority to control the render order of this camera. Cameras with a smaller + * priority value are rendered first. Defaults to 0. * * @type {number} */ @@ -557,12 +668,17 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets the priority to control the render order of this camera. + * + * @type {number} + */ get priority() { return this._priority; } /** - * The type of projection used to render the camera. Can be: + * Sets the type of projection used to render the camera. Can be: * * - {@link PROJECTION_PERSPECTIVE}: A perspective projection. The camera frustum * resembles a truncated pyramid. @@ -577,12 +693,17 @@ class CameraComponent extends Component { this._camera.projection = value; } + /** + * Gets the type of projection used to render the camera. + * + * @type {number} + */ get projection() { return this._camera.projection; } /** - * Queries the camera's projection matrix. + * Gets the camera's projection matrix. * * @type {import('../../../core/math/mat4.js').Mat4} */ @@ -591,8 +712,8 @@ class CameraComponent extends Component { } /** - * Controls where on the screen the camera will be rendered in normalized screen coordinates. - * Defaults to [0, 0, 1, 1]. + * Sets the rendering rectangle for the camera. This controls where on the screen the camera + * will render in normalized screen coordinates. Defaults to `[0, 0, 1, 1]`. * * @type {import('../../../core/math/vec4.js').Vec4} */ @@ -601,6 +722,11 @@ class CameraComponent extends Component { this.fire('set:rect', this._camera.rect); } + /** + * Gets the rendering rectangle for the camera. + * + * @type {import('../../../core/math/vec4.js').Vec4} + */ get rect() { return this._camera.rect; } @@ -634,8 +760,8 @@ class CameraComponent extends Component { } /** - * Render target to which rendering of the cameras is performed. If not set, it will render - * simply to the screen. + * Sets the render target to which rendering of the camera is performed. If not set, it will + * render simply to the screen. * * @type {import('../../../platform/graphics/render-target.js').RenderTarget} */ @@ -644,13 +770,18 @@ class CameraComponent extends Component { this.dirtyLayerCompositionCameras(); } + /** + * Gets the render target to which rendering of the camera is performed. + * + * @type {import('../../../platform/graphics/render-target.js').RenderTarget} + */ get renderTarget() { return this._camera.renderTarget; } /** - * Clips all pixels which are not in the rectangle. The order of the values is - * [x, y, width, height]. Defaults to [0, 0, 1, 1]. + * Sets the scissor rectangle for the camera. This clips all pixels which are not in the + * rectangle. The order of the values is `[x, y, width, height]`. Defaults to `[0, 0, 1, 1]`. * * @type {import('../../../core/math/vec4.js').Vec4} */ @@ -658,12 +789,17 @@ class CameraComponent extends Component { this._camera.scissorRect = value; } + /** + * Gets the scissor rectangle for the camera. + * + * @type {import('../../../core/math/vec4.js').Vec4} + */ get scissorRect() { return this._camera.scissorRect; } /** - * Set camera sensitivity in ISO, the default value is 1000. Higher value means more exposure. + * Sets the camera sensitivity in ISO. Defaults to 1000. Higher value means more exposure. * * @type {number} */ @@ -671,12 +807,17 @@ class CameraComponent extends Component { this._camera.sensitivity = value; } + /** + * Gets the camera sensitivity in ISO. + * + * @type {number} + */ get sensitivity() { return this._camera.sensitivity; } /** - * Set camera shutter speed in seconds, the default value is 1/1000s. Longer shutter means more exposure. + * Sets the camera shutter speed in seconds. Defaults to 1/1000s. Longer shutter means more exposure. * * @type {number} */ @@ -684,12 +825,17 @@ class CameraComponent extends Component { this._camera.shutter = value; } + /** + * Gets the camera shutter speed in seconds. + * + * @type {number} + */ get shutter() { return this._camera.shutter; } /** - * Queries the camera's view matrix. + * Gets the camera's view matrix. * * @type {import('../../../core/math/mat4.js').Mat4} */ diff --git a/src/framework/components/collision/component.js b/src/framework/components/collision/component.js index 2642d561731..56fdca259a1 100644 --- a/src/framework/components/collision/component.js +++ b/src/framework/components/collision/component.js @@ -130,24 +130,32 @@ class CollisionComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { this._setValue('enabled', arg); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } /** - * The type of the collision volume. Can be: + * Sets the type of the collision volume. Can be: * * - "box": A box-shaped collision volume. * - "capsule": A capsule-shaped collision volume. - * - "compound": A compound shape. Any descendant entities with a collision component of type - * box, capsule, cone, cylinder or sphere will be combined into a single, rigid shape. - * - "cone": A cone-shaped collision volume. - "cylinder": A cylinder-shaped collision volume. + * - "compound": A compound shape. Any descendant entities with a collision component of type + * box, capsule, cone, cylinder or sphere will be combined into a single, rigid shape. + * - "cone": A cone-shaped collision volume. + * - "cylinder": A cylinder-shaped collision volume. * - "mesh": A collision volume that uses a model asset as its shape. * - "sphere": A sphere-shaped collision volume. * @@ -159,13 +167,18 @@ class CollisionComponent extends Component { this._setValue('type', arg); } + /** + * Gets the type of the collision volume. + * + * @type {string} + */ get type() { return this.data.type; } /** - * The half-extents of the box-shaped collision volume in the x, y and z axes. Defaults to - * [0.5, 0.5, 0.5]. + * Sets the half-extents of the box-shaped collision volume in the x, y and z axes. Defaults to + * `[0.5, 0.5, 0.5]`. * * @type {Vec3} */ @@ -173,13 +186,18 @@ class CollisionComponent extends Component { this._setValue('halfExtents', arg); } + /** + * Gets the half-extents of the box-shaped collision volume in the x, y and z axes. + * + * @type {Vec3} + */ get halfExtents() { return this.data.halfExtents; } /** - * The positional offset of the collision shape from the Entity position along the local axes. - * Defaults to [0, 0, 0]. + * Sets the positional offset of the collision shape from the Entity position along the local + * axes. Defaults to `[0, 0, 0]`. * * @type {Vec3} */ @@ -187,12 +205,18 @@ class CollisionComponent extends Component { this._setValue('linearOffset', arg); } + /** + * Gets the positional offset of the collision shape from the Entity position along the local + * axes. + * + * @type {Vec3} + */ get linearOffset() { return this.data.linearOffset; } /** - * The rotational offset of the collision shape from the Entity rotation in local space. + * Sets the rotational offset of the collision shape from the Entity rotation in local space. * Defaults to identity. * * @type {Quat} @@ -201,12 +225,17 @@ class CollisionComponent extends Component { this._setValue('angularOffset', arg); } + /** + * Gets the rotational offset of the collision shape from the Entity rotation in local space. + * + * @type {Quat} + */ get angularOffset() { return this.data.angularOffset; } /** - * The radius of the sphere, capsule, cylinder or cone-shaped collision volumes. + * Sets the radius of the sphere, capsule, cylinder or cone-shaped collision volumes. * Defaults to 0.5. * * @type {number} @@ -215,12 +244,17 @@ class CollisionComponent extends Component { this._setValue('radius', arg); } + /** + * Gets the radius of the sphere, capsule, cylinder or cone-shaped collision volumes. + * + * @type {number} + */ get radius() { return this.data.radius; } /** - * The local space axis with which the capsule, cylinder or cone-shaped collision volume's + * Sets the local space axis with which the capsule, cylinder or cone-shaped collision volume's * length is aligned. 0 for X, 1 for Y and 2 for Z. Defaults to 1 (Y-axis). * * @type {number} @@ -229,13 +263,19 @@ class CollisionComponent extends Component { this._setValue('axis', arg); } + /** + * Gets the local space axis with which the capsule, cylinder or cone-shaped collision volume's + * length is aligned. + * + * @type {number} + */ get axis() { return this.data.axis; } /** - * The total height of the capsule, cylinder or cone-shaped collision volume from tip to tip. - * Defaults to 2. + * Sets the total height of the capsule, cylinder or cone-shaped collision volume from tip to + * tip. Defaults to 2. * * @type {number} */ @@ -243,41 +283,56 @@ class CollisionComponent extends Component { this._setValue('height', arg); } + /** + * Gets the total height of the capsule, cylinder or cone-shaped collision volume from tip to + * tip. + * + * @type {number} + */ get height() { return this.data.height; } /** - * The asset for the model of the mesh collision volume - can also be an asset id. Defaults to - * null. + * Sets the asset or asset id for the model of the mesh collision volume. Defaults to null. * - * @type {Asset} + * @type {Asset|number|null} */ set asset(arg) { this._setValue('asset', arg); } + /** + * Gets the asset or asset id for the model of the mesh collision volume. + * + * @type {Asset|number|null} + */ get asset() { return this.data.asset; } /** - * The render asset of the mesh collision volume - can also be an asset id. Defaults to null. + * Sets the render asset or asset id of the mesh collision volume. Defaults to null. * If not set then the asset property will be checked instead. * - * @type {Asset | number} + * @type {Asset|number|null} */ set renderAsset(arg) { this._setValue('renderAsset', arg); } + /** + * Gets the render asset id of the mesh collision volume. + * + * @type {Asset|number|null} + */ get renderAsset() { return this.data.renderAsset; } /** - * Whether the collision mesh should be treated as a convex hull. When false, the mesh can only - * be used with a static body. When true, the mesh can be used with a static, dynamic or + * Sets whether the collision mesh should be treated as a convex hull. When false, the mesh can + * only be used with a static body. When true, the mesh can be used with a static, dynamic or * kinematic body. Defaults to `false`. * * @type {boolean} @@ -286,14 +341,15 @@ class CollisionComponent extends Component { this._setValue('convexHull', arg); } + /** + * Gets whether the collision mesh should be treated as a convex hull. + * + * @type {boolean} + */ get convexHull() { return this.data.convexHull; } - /** - * @type {any} - * @ignore - */ set shape(arg) { this._setValue('shape', arg); } @@ -303,7 +359,7 @@ class CollisionComponent extends Component { } /** - * The model that is added to the scene graph for the mesh collision volume. + * Sets the model that is added to the scene graph for the mesh collision volume. * * @type {import('../../../scene/model.js').Model | null} */ @@ -311,14 +367,15 @@ class CollisionComponent extends Component { this._setValue('model', arg); } + /** + * Gets the model that is added to the scene graph for the mesh collision volume. + * + * @type {import('../../../scene/model.js').Model | null} + */ get model() { return this.data.model; } - /** - * @type {any} - * @ignore - */ set render(arg) { this._setValue('render', arg); } @@ -328,7 +385,7 @@ class CollisionComponent extends Component { } /** - * Enable checking for duplicate vertices. + * Sets whether checking for duplicate vertices should be enabled when creating collision meshes. * * @type {boolean} */ @@ -336,6 +393,11 @@ class CollisionComponent extends Component { this._setValue('checkVertexDuplicates', arg); } + /** + * Gets whether checking for duplicate vertices should be enabled when creating collision meshes. + * + * @type {boolean} + */ get checkVertexDuplicates() { return this.data.checkVertexDuplicates; } @@ -636,7 +698,8 @@ class CollisionComponent extends Component { } /** - * @description Returns the world position for the collision shape taking into account of any offsets. + * Returns the world position for the collision shape, taking into account of any offsets. + * * @returns {Vec3} The world position for the collision shape. */ getShapePosition() { @@ -654,7 +717,8 @@ class CollisionComponent extends Component { } /** - * @description Returns the world rotation for the collision shape taking into account of any offsets. + * Returns the world rotation for the collision shape, taking into account of any offsets. + * * @returns {Quat} The world rotation for the collision. */ getShapeRotation() { diff --git a/src/framework/components/component.js b/src/framework/components/component.js index ca3bee8685d..a034fa226fc 100644 --- a/src/framework/components/component.js +++ b/src/framework/components/component.js @@ -112,13 +112,18 @@ class Component extends EventHandler { } /** - * Enables or disables the component. + * Sets the enabled state of the component. * * @type {boolean} */ set enabled(arg) { } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return true; } diff --git a/src/framework/components/element/component.js b/src/framework/components/element/component.js index ba26dba5d87..46397f3d6c4 100644 --- a/src/framework/components/element/component.js +++ b/src/framework/components/element/component.js @@ -43,7 +43,7 @@ const matD = new Mat4(); * * ```javascript * // Add an element component to an entity with the default options - * let entity = pc.Entity(); + * const entity = pc.Entity(); * entity.addComponent("element"); // This defaults to a 'group' element * ``` * @@ -257,7 +257,7 @@ class ElementComponent extends Component { // Order is bottom left, bottom right, top right, top left this._canvasCorners = [new Vec2(), new Vec2(), new Vec2(), new Vec2()]; - // the world-space corners of the element + // the world space corners of the element // Order is bottom left, bottom right, top right, top left this._worldCorners = [new Vec3(), new Vec3(), new Vec3(), new Vec3()]; @@ -317,6 +317,8 @@ class ElementComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(value) { @@ -326,6 +328,11 @@ class ElementComponent extends Component { this.fire('set', 'enabled', oldValue, value); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } @@ -379,6 +386,8 @@ class ElementComponent extends Component { } /** + * Gets the world space axis-aligned bounding box for this element component. + * * @type {import('../../../core/shape/bounding-box.js').BoundingBox | null} */ get aabb() { @@ -393,17 +402,18 @@ class ElementComponent extends Component { } /** - * Specifies where the left, bottom, right and top edges of the component are anchored relative - * to its parent. Each value ranges from 0 to 1. e.g. a value of [0, 0, 0, 0] means that the - * element will be anchored to the bottom left of its parent. A value of [1, 1, 1, 1] means it - * will be anchored to the top right. A split anchor is when the left-right or top-bottom pairs - * of the anchor are not equal. In that case the component will be resized to cover that entire - * area. e.g. a value of [0, 0, 1, 1] will make the component resize exactly as its parent. + * Sets the anchor for this element component. Specifies where the left, bottom, right and top + * edges of the component are anchored relative to its parent. Each value ranges from 0 to 1. + * e.g. a value of `[0, 0, 0, 0]` means that the element will be anchored to the bottom left of + * its parent. A value of `[1, 1, 1, 1]` means it will be anchored to the top right. A split + * anchor is when the left-right or top-bottom pairs of the anchor are not equal. In that case, + * the component will be resized to cover that entire area. For example, a value of `[0, 0, 1, 1]` + * will make the component resize exactly as its parent. * * @example - * pc.app.root.findByName("Inventory").element.anchor = new pc.Vec4(Math.random() * 0.1, 0, 1, 0); + * this.entity.element.anchor = new pc.Vec4(Math.random() * 0.1, 0, 1, 0); * @example - * pc.app.root.findByName("Inventory").element.anchor = [Math.random() * 0.1, 0, 1, 0]; + * this.entity.element.anchor = [Math.random() * 0.1, 0, 1, 0]; * * @type {Vec4 | number[]} */ @@ -429,12 +439,17 @@ class ElementComponent extends Component { this.fire('set:anchor', this._anchor); } + /** + * Gets the anchor for this element component. + * + * @type {Vec4 | number[]} + */ get anchor() { return this._anchor; } /** - * Assign element to a specific batch group (see {@link BatchGroup}). Default is -1 (no group). + * Sets the batch group (see {@link BatchGroup}) for this element. Default is -1 (no group). * * @type {number} */ @@ -463,13 +478,18 @@ class ElementComponent extends Component { this._batchGroupId = value; } + /** + * Gets the batch group (see {@link BatchGroup}) for this element. + * + * @type {number} + */ get batchGroupId() { return this._batchGroupId; } /** - * The distance from the bottom edge of the anchor. Can be used in combination with a split - * anchor to make the component's top edge always be 'top' units away from the top. + * Sets the distance from the bottom edge of the anchor. Can be used in combination with a + * split anchor to make the component's top edge always be 'top' units away from the top. * * @type {number} */ @@ -484,16 +504,21 @@ class ElementComponent extends Component { this.entity.setLocalPosition(p); } + /** + * Gets the distance from the bottom edge of the anchor. + * + * @type {number} + */ get bottom() { return this._margin.y; } /** - * The width at which the element will be rendered. In most cases this will be the same as - * `width`. However, in some cases the engine may calculate a different width for the element, - * such as when the element is under the control of a {@link LayoutGroupComponent}. In these - * scenarios, `calculatedWidth` may be smaller or larger than the width that was set in the - * editor. + * Sets the width at which the element will be rendered. In most cases this will be the same as + * {@link width}. However, in some cases the engine may calculate a different width for the + * element, such as when the element is under the control of a {@link LayoutGroupComponent}. In + * these scenarios, `calculatedWidth` may be smaller or larger than the width that was set in + * the editor. * * @type {number} */ @@ -501,16 +526,21 @@ class ElementComponent extends Component { this._setCalculatedWidth(value, true); } + /** + * Gets the width at which the element will be rendered. + * + * @type {number} + */ get calculatedWidth() { return this._calculatedWidth; } /** - * The height at which the element will be rendered. In most cases this will be the same as - * `height`. However, in some cases the engine may calculate a different height for the element, - * such as when the element is under the control of a {@link LayoutGroupComponent}. In these - * scenarios, `calculatedHeight` may be smaller or larger than the height that was set in the - * editor. + * Sets the height at which the element will be rendered. In most cases this will be the same + * as {@link height}. However, in some cases the engine may calculate a different height for + * the element, such as when the element is under the control of a {@link LayoutGroupComponent}. + * In these scenarios, `calculatedHeight` may be smaller or larger than the height that was set + * in the editor. * * @type {number} */ @@ -518,13 +548,18 @@ class ElementComponent extends Component { this._setCalculatedHeight(value, true); } + /** + * Gets the height at which the element will be rendered. + * + * @type {number} + */ get calculatedHeight() { return this._calculatedHeight; } /** - * An array of 4 {@link Vec2}s that represent the bottom left, bottom right, top right and top - * left corners of the component in canvas pixels. Only works for screen space element + * Gets the array of 4 {@link Vec2}s that represent the bottom left, bottom right, top right + * and top left corners of the component in canvas pixels. Only works for screen space element * components. * * @type {Vec2[]} @@ -550,8 +585,8 @@ class ElementComponent extends Component { } /** - * The draw order of the component. A higher value means that the component will be rendered on - * top of other components. + * Sets the draw order of the component. A higher value means that the component will be + * rendered on top of other components. * * @type {number} */ @@ -571,15 +606,20 @@ class ElementComponent extends Component { this.fire('set:draworder', this._drawOrder); } + /** + * Gets the draw order of the component. + * + * @type {number} + */ get drawOrder() { return this._drawOrder; } /** - * The height of the element as set in the editor. Note that in some cases this may not reflect - * the true height at which the element is rendered, such as when the element is under the - * control of a {@link LayoutGroupComponent}. See `calculatedHeight` in order to ensure you are - * reading the true height at which the element will be rendered. + * Sets the height of the element as set in the editor. Note that in some cases this may not + * reflect the true height at which the element is rendered, such as when the element is under + * the control of a {@link LayoutGroupComponent}. See {@link calculatedHeight} in order to + * ensure you are reading the true height at which the element will be rendered. * * @type {number} */ @@ -593,13 +633,18 @@ class ElementComponent extends Component { this.fire('set:height', this._height); } + /** + * Gets the height of the element. + * + * @type {number} + */ get height() { return this._height; } /** - * An array of layer IDs ({@link Layer#id}) to which this element should belong. Don't push, - * pop, splice or modify this array, if you want to change it - set a new one instead. + * Sets the array of layer IDs ({@link Layer#id}) to which this element should belong. Don't + * push, pop, splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -631,12 +676,17 @@ class ElementComponent extends Component { } } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this element belongs. + * + * @type {number[]} + */ get layers() { return this._layers; } /** - * The distance from the left edge of the anchor. Can be used in combination with a split + * Sets the distance from the left edge of the anchor. Can be used in combination with a split * anchor to make the component's left edge always be 'left' units away from the left. * * @type {number} @@ -652,14 +702,19 @@ class ElementComponent extends Component { this.entity.setLocalPosition(p); } + /** + * Gets the distance from the left edge of the anchor. + * + * @type {number} + */ get left() { return this._margin.x; } /** - * The distance from the left, bottom, right and top edges of the anchor. For example if we are - * using a split anchor like [0,0,1,1] and the margin is [0,0,0,0] then the component will be - * the same width and height as its parent. + * Sets the distance from the left, bottom, right and top edges of the anchor. For example, if + * we are using a split anchor like `[0, 0, 1, 1]` and the margin is `[0, 0, 0, 0]` then the + * component will be the same width and height as its parent. * * @type {Vec4} */ @@ -669,12 +724,17 @@ class ElementComponent extends Component { this.fire('set:margin', this._margin); } + /** + * Gets the distance from the left, bottom, right and top edges of the anchor. + * + * @type {Vec4} + */ get margin() { return this._margin; } /** - * Get the entity that is currently masking this element. + * Gets the entity that is currently masking this element. * * @type {Entity} * @private @@ -684,13 +744,13 @@ class ElementComponent extends Component { } /** - * The position of the pivot of the component relative to its anchor. Each value ranges from 0 - * to 1 where [0,0] is the bottom left and [1,1] is the top right. + * Sets the position of the pivot of the component relative to its anchor. Each value ranges + * from 0 to 1 where `[0, 0]` is the bottom left and `[1, 1]` is the top right. * * @example - * pc.app.root.findByName("Inventory").element.pivot = [Math.random() * 0.1, Math.random() * 0.1]; + * this.entity.element.pivot = [Math.random() * 0.1, Math.random() * 0.1]; * @example - * pc.app.root.findByName("Inventory").element.pivot = new pc.Vec2(Math.random() * 0.1, Math.random() * 0.1); + * this.entity.element.pivot = new pc.Vec2(Math.random() * 0.1, Math.random() * 0.1); * * @type {Vec2 | number[]} */ @@ -728,12 +788,17 @@ class ElementComponent extends Component { this.fire('set:pivot', pivot); } + /** + * Gets the position of the pivot of the component relative to its anchor. + * + * @type {Vec2 | number[]} + */ get pivot() { return this._pivot; } /** - * The distance from the right edge of the anchor. Can be used in combination with a split + * Sets the distance from the right edge of the anchor. Can be used in combination with a split * anchor to make the component's right edge always be 'right' units away from the right. * * @type {number} @@ -752,13 +817,18 @@ class ElementComponent extends Component { this.entity.setLocalPosition(p); } + /** + * Gets the distance from the right edge of the anchor. + * + * @type {number} + */ get right() { return this._margin.z; } /** - * An array of 4 {@link Vec3}s that represent the bottom left, bottom right, top right and top - * left corners of the component relative to its parent {@link ScreenComponent}. + * Gets the array of 4 {@link Vec3}s that represent the bottom left, bottom right, top right + * and top left corners of the component relative to its parent {@link ScreenComponent}. * * @type {Vec3[]} */ @@ -796,7 +866,8 @@ class ElementComponent extends Component { } /** - * The width of the text rendered by the component. Only works for {@link ELEMENTTYPE_TEXT} types. + * Gets the width of the text rendered by the component. Only works for + * {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -805,7 +876,8 @@ class ElementComponent extends Component { } /** - * The height of the text rendered by the component. Only works for {@link ELEMENTTYPE_TEXT} types. + * Gets the height of the text rendered by the component. Only works for + * {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -814,8 +886,8 @@ class ElementComponent extends Component { } /** - * The distance from the top edge of the anchor. Can be used in combination with a split anchor - * to make the component's bottom edge always be 'bottom' units away from the bottom. + * Sets the distance from the top edge of the anchor. Can be used in combination with a split + * anchor to make the component's bottom edge always be 'bottom' units away from the bottom. * * @type {number} */ @@ -830,15 +902,20 @@ class ElementComponent extends Component { this.entity.setLocalPosition(p); } + /** + * Gets the distance from the top edge of the anchor. + * + * @type {number} + */ get top() { return this._margin.w; } /** - * The type of the ElementComponent. Can be: + * Sets the type of the ElementComponent. Can be: * - * - {@link ELEMENTTYPE_GROUP}: The component can be used as a layout mechanism to create groups of - * ElementComponents e.g. panels. + * - {@link ELEMENTTYPE_GROUP}: The component can be used as a layout mechanism to create + * groups of ElementComponents e.g. panels. * - {@link ELEMENTTYPE_IMAGE}: The component will render an image * - {@link ELEMENTTYPE_TEXT}: The component will render text * @@ -865,12 +942,17 @@ class ElementComponent extends Component { } } + /** + * Gets the type of the ElementComponent. + * + * @type {string} + */ get type() { return this._type; } /** - * If true then the component will receive Mouse or Touch input events. + * Sets whether the component will receive mouse and touch input events. * * @type {boolean} */ @@ -898,17 +980,25 @@ class ElementComponent extends Component { this.fire('set:useInput', value); } + /** + * Gets whether the component will receive mouse and touch input events. + * + * @type {boolean} + */ get useInput() { return this._useInput; } /** - * Set how the content should be fitted and preserve the aspect ratio of the source texture or sprite. - * Only works for {@link ELEMENTTYPE_IMAGE} types. Can be: + * Sets the fit mode of the element. Controls how the content should be fitted and preserve the + * aspect ratio of the source texture or sprite. Only works for {@link ELEMENTTYPE_IMAGE} + * types. Can be: * * - {@link FITMODE_STRETCH}: Fit the content exactly to Element's bounding box. - * - {@link FITMODE_CONTAIN}: Fit the content within the Element's bounding box while preserving its Aspect Ratio. - * - {@link FITMODE_COVER}: Fit the content to cover the entire Element's bounding box while preserving its Aspect Ratio. + * - {@link FITMODE_CONTAIN}: Fit the content within the Element's bounding box while + * preserving its Aspect Ratio. + * - {@link FITMODE_COVER}: Fit the content to cover the entire Element's bounding box while + * preserving its Aspect Ratio. * * @type {string} */ @@ -920,15 +1010,20 @@ class ElementComponent extends Component { } } + /** + * Gets the fit mode of the element. + * + * @type {string} + */ get fitMode() { return this._fitMode; } /** - * The width of the element as set in the editor. Note that in some cases this may not reflect - * the true width at which the element is rendered, such as when the element is under the - * control of a {@link LayoutGroupComponent}. See `calculatedWidth` in order to ensure you are - * reading the true width at which the element will be rendered. + * Sets the width of the element as set in the editor. Note that in some cases this may not + * reflect the true width at which the element is rendered, such as when the element is under + * the control of a {@link LayoutGroupComponent}. See {@link calculatedWidth} in order to + * ensure you are reading the true width at which the element will be rendered. * * @type {number} */ @@ -942,13 +1037,18 @@ class ElementComponent extends Component { this.fire('set:width', this._width); } + /** + * Gets the width of the element. + * + * @type {number} + */ get width() { return this._width; } /** - * An array of 4 {@link Vec3}s that represent the bottom left, bottom right, top right and top - * left corners of the component in world space. Only works for 3D element components. + * Gets the array of 4 {@link Vec3}s that represent the bottom left, bottom right, top right + * and top left corners of the component in world space. Only works for 3D element components. * * @type {Vec3[]} */ @@ -1010,7 +1110,7 @@ class ElementComponent extends Component { } /** - * The size of the font. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the size of the font. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1018,6 +1118,11 @@ class ElementComponent extends Component { this._setValue('fontSize', arg); } + /** + * Gets the size of the font. + * + * @type {number} + */ get fontSize() { if (this._text) { return this._text.fontSize; @@ -1027,7 +1132,8 @@ class ElementComponent extends Component { } /** - * The minimum size that the font can scale to when autoFitWidth or autoFitHeight are true. + * Sets the minimum size that the font can scale to when {@link autoFitWidth} or + * {@link autoFitHeight} are true. * * @type {number} */ @@ -1035,6 +1141,12 @@ class ElementComponent extends Component { this._setValue('minFontSize', arg); } + /** + * Gets the minimum size that the font can scale to when {@link autoFitWidth} or + * {@link autoFitHeight} are true. + * + * @type {number} + */ get minFontSize() { if (this._text) { return this._text.minFontSize; @@ -1044,7 +1156,8 @@ class ElementComponent extends Component { } /** - * The maximum size that the font can scale to when autoFitWidth or autoFitHeight are true. + * Sets the maximum size that the font can scale to when {@link autoFitWidth} or + * {@link autoFitHeight} are true. * * @type {number} */ @@ -1052,6 +1165,12 @@ class ElementComponent extends Component { this._setValue('maxFontSize', arg); } + /** + * Gets the maximum size that the font can scale to when {@link autoFitWidth} or + * {@link autoFitHeight} are true. + * + * @type {number} + */ get maxFontSize() { if (this._text) { return this._text.maxFontSize; @@ -1061,15 +1180,21 @@ class ElementComponent extends Component { } /** - * The maximum number of lines that the Element can wrap to. Any leftover text will be appended - * to the last line. Set this to null to allow unlimited lines. + * Sets the maximum number of lines that the Element can wrap to. Any leftover text will be + * appended to the last line. Set this to null to allow unlimited lines. * - * @type {number} + * @type {number|null} */ set maxLines(arg) { this._setValue('maxLines', arg); } + /** + * Gets the maximum number of lines that the Element can wrap to. Returns null for unlimited + * lines. + * + * @type {number|null} + */ get maxLines() { if (this._text) { return this._text.maxLines; @@ -1079,9 +1204,10 @@ class ElementComponent extends Component { } /** - * When true the font size and line height will scale so that the text fits inside the width of - * the Element. The font size will be scaled between minFontSize and maxFontSize. The value of - * autoFitWidth will be ignored if autoWidth is true. + * Sets whether the font size and line height will scale so that the text fits inside the width + * of the Element. The font size will be scaled between {@link minFontSize} and + * {@link maxFontSize}. The value of {@link autoFitWidth} will be ignored if {@link autoWidth} + * is true. * * @type {boolean} */ @@ -1089,6 +1215,12 @@ class ElementComponent extends Component { this._setValue('autoFitWidth', arg); } + /** + * Gets whether the font size and line height will scale so that the text fits inside the width + * of the Element. + * + * @type {boolean} + */ get autoFitWidth() { if (this._text) { return this._text.autoFitWidth; @@ -1098,9 +1230,10 @@ class ElementComponent extends Component { } /** - * When true the font size and line height will scale so that the text fits inside the height of - * the Element. The font size will be scaled between minFontSize and maxFontSize. The value of - * autoFitHeight will be ignored if autoHeight is true. + * Sets whether the font size and line height will scale so that the text fits inside the + * height of the Element. The font size will be scaled between {@link minFontSize} and + * {@link maxFontSize}. The value of {@link autoFitHeight} will be ignored if + * {@link autoHeight} is true. * * @type {boolean} */ @@ -1108,6 +1241,12 @@ class ElementComponent extends Component { this._setValue('autoFitHeight', arg); } + /** + * Gets whether the font size and line height will scale so that the text fits inside the + * height of the Element. + * + * @type {boolean} + */ get autoFitHeight() { if (this._text) { return this._text.autoFitHeight; @@ -1117,7 +1256,7 @@ class ElementComponent extends Component { } /** - * The color of the image for {@link ELEMENTTYPE_IMAGE} types or the color of the text for + * Sets the color of the image for {@link ELEMENTTYPE_IMAGE} types or the color of the text for * {@link ELEMENTTYPE_TEXT} types. * * @type {import('../../../core/math/color.js').Color} @@ -1126,6 +1265,11 @@ class ElementComponent extends Component { this._setValue('color', arg); } + /** + * Gets the color of the element. + * + * @type {import('../../../core/math/color.js').Color} + */ get color() { if (this._text) { return this._text.color; @@ -1139,7 +1283,7 @@ class ElementComponent extends Component { } /** - * The font used for rendering the text. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the font used for rendering the text. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {import('../../../framework/font/font.js').Font | import('../../../framework/font/canvas-font.js').CanvasFont} */ @@ -1147,6 +1291,11 @@ class ElementComponent extends Component { this._setValue('font', arg); } + /** + * Gets the font used for rendering the text. + * + * @type {import('../../../framework/font/font.js').Font | import('../../../framework/font/canvas-font.js').CanvasFont} + */ get font() { if (this._text) { return this._text.font; @@ -1156,7 +1305,7 @@ class ElementComponent extends Component { } /** - * The id of the font asset used for rendering the text. Only works for {@link ELEMENTTYPE_TEXT} + * Sets the id of the font asset used for rendering the text. Only works for {@link ELEMENTTYPE_TEXT} * types. * * @type {number} @@ -1165,6 +1314,11 @@ class ElementComponent extends Component { this._setValue('fontAsset', arg); } + /** + * Gets the id of the font asset used for rendering the text. + * + * @type {number} + */ get fontAsset() { if (this._text && typeof this._text.fontAsset === 'number') { return this._text.fontAsset; @@ -1174,7 +1328,7 @@ class ElementComponent extends Component { } /** - * The spacing between the letters of the text. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the spacing between the letters of the text. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1182,6 +1336,11 @@ class ElementComponent extends Component { this._setValue('spacing', arg); } + /** + * Gets the spacing between the letters of the text. + * + * @type {number} + */ get spacing() { if (this._text) { return this._text.spacing; @@ -1191,7 +1350,7 @@ class ElementComponent extends Component { } /** - * The height of each line of text. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the height of each line of text. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1199,6 +1358,11 @@ class ElementComponent extends Component { this._setValue('lineHeight', arg); } + /** + * Gets the height of each line of text. + * + * @type {number} + */ get lineHeight() { if (this._text) { return this._text.lineHeight; @@ -1208,8 +1372,8 @@ class ElementComponent extends Component { } /** - * Whether to automatically wrap lines based on the element width. Only works for - * {@link ELEMENTTYPE_TEXT} types, and when autoWidth is set to false. + * Sets whether to automatically wrap lines based on the element width. Only works for + * {@link ELEMENTTYPE_TEXT} types, and when {@link autoWidth} is set to false. * * @type {boolean} */ @@ -1217,6 +1381,11 @@ class ElementComponent extends Component { this._setValue('wrapLines', arg); } + /** + * Gets whether to automatically wrap lines based on the element width. + * + * @type {boolean} + */ get wrapLines() { if (this._text) { return this._text.wrapLines; @@ -1225,17 +1394,10 @@ class ElementComponent extends Component { return null; } - /** - * @type {any} - * @ignore - */ set lines(arg) { this._setValue('lines', arg); } - /** - * @ignore - */ get lines() { if (this._text) { return this._text.lines; @@ -1245,8 +1407,9 @@ class ElementComponent extends Component { } /** - * The horizontal and vertical alignment of the text. Values range from 0 to 1 where [0,0] is - * the bottom left and [1,1] is the top right. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the horizontal and vertical alignment of the text. Values range from 0 to 1 where + * `[0, 0]` is the bottom left and `[1, 1]` is the top right. Only works for + * {@link ELEMENTTYPE_TEXT} types. * * @type {Vec2} */ @@ -1254,6 +1417,11 @@ class ElementComponent extends Component { this._setValue('alignment', arg); } + /** + * Gets the horizontal and vertical alignment of the text. + * + * @type {Vec2} + */ get alignment() { if (this._text) { return this._text.alignment; @@ -1263,8 +1431,8 @@ class ElementComponent extends Component { } /** - * Automatically set the width of the component to be the same as the textWidth. Only works for - * {@link ELEMENTTYPE_TEXT} types. + * Sets whether to automatically set the width of the component to be the same as the + * {@link textWidth}. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {boolean} */ @@ -1272,6 +1440,12 @@ class ElementComponent extends Component { this._setValue('autoWidth', arg); } + /** + * Gets whether to automatically set the width of the component to be the same as the + * {@link textWidth}. + * + * @type {boolean} + */ get autoWidth() { if (this._text) { return this._text.autoWidth; @@ -1281,8 +1455,8 @@ class ElementComponent extends Component { } /** - * Automatically set the height of the component to be the same as the textHeight. Only works - * for {@link ELEMENTTYPE_TEXT} types. + * Sets whether to automatically set the height of the component to be the same as the + * {@link textHeight}. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {boolean} */ @@ -1290,6 +1464,12 @@ class ElementComponent extends Component { this._setValue('autoHeight', arg); } + /** + * Gets whether to automatically set the height of the component to be the same as the + * {@link textHeight}. + * + * @type {boolean} + */ get autoHeight() { if (this._text) { return this._text.autoHeight; @@ -1299,8 +1479,8 @@ class ElementComponent extends Component { } /** - * Reorder the text for RTL languages using a function registered by - * `app.systems.element.registerUnicodeConverter`. + * Sets whether to reorder the text for RTL languages. The reordering uses a function + * registered by `app.systems.element.registerUnicodeConverter`. * * @type {boolean} */ @@ -1308,6 +1488,11 @@ class ElementComponent extends Component { this._setValue('rtlReorder', arg); } + /** + * Gets whether to reorder the text for RTL languages. + * + * @type {boolean} + */ get rtlReorder() { if (this._text) { return this._text.rtlReorder; @@ -1317,7 +1502,8 @@ class ElementComponent extends Component { } /** - * Convert unicode characters using a function registered by `app.systems.element.registerUnicodeConverter`. + * Sets whether to convert unicode characters. This uses a function registered by + * `app.systems.element.registerUnicodeConverter`. * * @type {boolean} */ @@ -1325,6 +1511,11 @@ class ElementComponent extends Component { this._setValue('unicodeConverter', arg); } + /** + * Gets whether to convert unicode characters. + * + * @type {boolean} + */ get unicodeConverter() { if (this._text) { return this._text.unicodeConverter; @@ -1334,22 +1525,24 @@ class ElementComponent extends Component { } /** - * The text to render. Only works for {@link ELEMENTTYPE_TEXT} types. To - * override certain text styling properties on a per-character basis, the text can optionally - * include markup tags contained within square brackets. Supported tags are: + * Sets the text to render. Only works for {@link ELEMENTTYPE_TEXT} types. To override certain + * text styling properties on a per-character basis, the text can optionally include markup + * tags contained within square brackets. Supported tags are: * - * 1. `color` - override the element's `color` property. Examples: - * - `[color="#ff0000"]red text[/color]` - * - `[color="#00ff00"]green text[/color]` - * - `[color="#0000ff"]blue text[/color]` - * 2. `outline` - override the element's `outlineColor` and `outlineThickness` properties. Example: - * - `[outline color="#ffffff" thickness="0.5"]text[/outline]` - * 3. `shadow` - override the element's `shadowColor` and `shadowOffset` properties. Examples: - * - `[shadow color="#ffffff" offset="0.5"]text[/shadow]` - * - `[shadow color="#000000" offsetX="0.1" offsetY="0.2"]text[/shadow]` + * 1. `color` - override the element's {@link color} property. Examples: + * - `[color="#ff0000"]red text[/color]` + * - `[color="#00ff00"]green text[/color]` + * - `[color="#0000ff"]blue text[/color]` + * 2. `outline` - override the element's {@link outlineColor} and {@link outlineThickness} + * properties. Example: + * - `[outline color="#ffffff" thickness="0.5"]text[/outline]` + * 3. `shadow` - override the element's {@link shadowColor} and {@link shadowOffset} + * properties. Examples: + * - `[shadow color="#ffffff" offset="0.5"]text[/shadow]` + * - `[shadow color="#000000" offsetX="0.1" offsetY="0.2"]text[/shadow]` * - * Note that markup tags are only processed if the text element's `enableMarkup` property is set to - * true. + * Note that markup tags are only processed if the text element's {@link enableMarkup} property + * is set to true. * * @type {string} */ @@ -1357,6 +1550,11 @@ class ElementComponent extends Component { this._setValue('text', arg); } + /** + * Gets the text to render. + * + * @type {string} + */ get text() { if (this._text) { return this._text.text; @@ -1366,8 +1564,8 @@ class ElementComponent extends Component { } /** - * The localization key to use to get the localized text from {@link Application#i18n}. Only - * works for {@link ELEMENTTYPE_TEXT} types. + * Sets the localization key to use to get the localized text from {@link Application#i18n}. + * Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {string} */ @@ -1375,6 +1573,11 @@ class ElementComponent extends Component { this._setValue('key', arg); } + /** + * Gets the localization key to use to get the localized text from {@link Application#i18n}. + * + * @type {string} + */ get key() { if (this._text) { return this._text.key; @@ -1384,7 +1587,7 @@ class ElementComponent extends Component { } /** - * The texture to render. Only works for {@link ELEMENTTYPE_IMAGE} types. + * Sets the texture to render. Only works for {@link ELEMENTTYPE_IMAGE} types. * * @type {import('../../../platform/graphics/texture.js').Texture} */ @@ -1392,6 +1595,11 @@ class ElementComponent extends Component { this._setValue('texture', arg); } + /** + * Gets the texture to render. + * + * @type {import('../../../platform/graphics/texture.js').Texture} + */ get texture() { if (this._image) { return this._image.texture; @@ -1401,7 +1609,7 @@ class ElementComponent extends Component { } /** - * The id of the texture asset to render. Only works for {@link ELEMENTTYPE_IMAGE} types. + * Sets the id of the texture asset to render. Only works for {@link ELEMENTTYPE_IMAGE} types. * * @type {number} */ @@ -1409,6 +1617,11 @@ class ElementComponent extends Component { this._setValue('textureAsset', arg); } + /** + * Gets the id of the texture asset to render. + * + * @type {number} + */ get textureAsset() { if (this._image) { return this._image.textureAsset; @@ -1418,7 +1631,7 @@ class ElementComponent extends Component { } /** - * The material to use when rendering an image. Only works for {@link ELEMENTTYPE_IMAGE} types. + * Sets the material to use when rendering an image. Only works for {@link ELEMENTTYPE_IMAGE} types. * * @type {import('../../../scene/materials/material.js').Material} */ @@ -1426,6 +1639,11 @@ class ElementComponent extends Component { this._setValue('material', arg); } + /** + * Gets the material to use when rendering an image. + * + * @type {import('../../../scene/materials/material.js').Material} + */ get material() { if (this._image) { return this._image.material; @@ -1435,7 +1653,7 @@ class ElementComponent extends Component { } /** - * The id of the material asset to use when rendering an image. Only works for + * Sets the id of the material asset to use when rendering an image. Only works for * {@link ELEMENTTYPE_IMAGE} types. * * @type {number} @@ -1444,6 +1662,11 @@ class ElementComponent extends Component { this._setValue('materialAsset', arg); } + /** + * Gets the id of the material asset to use when rendering an image. + * + * @type {number} + */ get materialAsset() { if (this._image) { return this._image.materialAsset; @@ -1453,8 +1676,8 @@ class ElementComponent extends Component { } /** - * The sprite to render. Only works for {@link ELEMENTTYPE_IMAGE} types which can render either - * a texture or a sprite. + * Sets the sprite to render. Only works for {@link ELEMENTTYPE_IMAGE} types which can render + * either a texture or a sprite. * * @type {import('../../../scene/sprite.js').Sprite} */ @@ -1462,6 +1685,11 @@ class ElementComponent extends Component { this._setValue('sprite', arg); } + /** + * Gets the sprite to render. + * + * @type {import('../../../scene/sprite.js').Sprite} + */ get sprite() { if (this._image) { return this._image.sprite; @@ -1471,7 +1699,7 @@ class ElementComponent extends Component { } /** - * The id of the sprite asset to render. Only works for {@link ELEMENTTYPE_IMAGE} types which + * Sets the id of the sprite asset to render. Only works for {@link ELEMENTTYPE_IMAGE} types which * can render either a texture or a sprite. * * @type {number} @@ -1480,6 +1708,11 @@ class ElementComponent extends Component { this._setValue('spriteAsset', arg); } + /** + * Gets the id of the sprite asset to render. + * + * @type {number} + */ get spriteAsset() { if (this._image) { return this._image.spriteAsset; @@ -1489,7 +1722,7 @@ class ElementComponent extends Component { } /** - * The frame of the sprite to render. Only works for {@link ELEMENTTYPE_IMAGE} types who have a + * Sets the frame of the sprite to render. Only works for {@link ELEMENTTYPE_IMAGE} types who have a * sprite assigned. * * @type {number} @@ -1498,6 +1731,11 @@ class ElementComponent extends Component { this._setValue('spriteFrame', arg); } + /** + * Gets the frame of the sprite to render. + * + * @type {number} + */ get spriteFrame() { if (this._image) { return this._image.spriteFrame; @@ -1507,7 +1745,7 @@ class ElementComponent extends Component { } /** - * The number of pixels that map to one PlayCanvas unit. Only works for + * Sets the number of pixels that map to one PlayCanvas unit. Only works for * {@link ELEMENTTYPE_IMAGE} types who have a sliced sprite assigned. * * @type {number} @@ -1516,6 +1754,11 @@ class ElementComponent extends Component { this._setValue('pixelsPerUnit', arg); } + /** + * Gets the number of pixels that map to one PlayCanvas unit. + * + * @type {number} + */ get pixelsPerUnit() { if (this._image) { return this._image.pixelsPerUnit; @@ -1525,8 +1768,8 @@ class ElementComponent extends Component { } /** - * The opacity of the image for {@link ELEMENTTYPE_IMAGE} types or the text for - * {@link ELEMENTTYPE_TEXT} types. + * Sets the opacity of the element. This works for both {@link ELEMENTTYPE_IMAGE} and + * {@link ELEMENTTYPE_TEXT} element types. * * @type {number} */ @@ -1534,6 +1777,11 @@ class ElementComponent extends Component { this._setValue('opacity', arg); } + /** + * Gets the opacity of the element. + * + * @type {number} + */ get opacity() { if (this._text) { return this._text.opacity; @@ -1547,8 +1795,8 @@ class ElementComponent extends Component { } /** - * Specifies which region of the texture to use in order to render an image. Values range from 0 - * to 1 and indicate u, v, width, height. Only works for {@link ELEMENTTYPE_IMAGE} types. + * Sets the region of the texture to use in order to render an image. Values range from 0 to 1 + * and indicate u, v, width, height. Only works for {@link ELEMENTTYPE_IMAGE} types. * * @type {Vec4} */ @@ -1556,6 +1804,11 @@ class ElementComponent extends Component { this._setValue('rect', arg); } + /** + * Gets the region of the texture to use in order to render an image. + * + * @type {Vec4} + */ get rect() { if (this._image) { return this._image.rect; @@ -1565,8 +1818,8 @@ class ElementComponent extends Component { } /** - * Switch Image Element into a mask. Masks do not render into the scene, but instead limit child - * elements to only be rendered where this element is rendered. + * Sets whether the Image Element should be treated as a mask. Masks do not render into the + * scene, but instead limit child elements to only be rendered where this element is rendered. * * @type {boolean} */ @@ -1574,6 +1827,11 @@ class ElementComponent extends Component { this._setValue('mask', arg); } + /** + * Gets whether the Image Element should be treated as a mask. + * + * @type {boolean} + */ get mask() { if (this._image) { return this._image.mask; @@ -1583,7 +1841,7 @@ class ElementComponent extends Component { } /** - * The text outline effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the text outline effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {import('../../../core/math/color.js').Color} */ @@ -1591,6 +1849,11 @@ class ElementComponent extends Component { this._setValue('outlineColor', arg); } + /** + * Gets the text outline effect color and opacity. + * + * @type {import('../../../core/math/color.js').Color} + */ get outlineColor() { if (this._text) { return this._text.outlineColor; @@ -1599,7 +1862,7 @@ class ElementComponent extends Component { } /** - * The width of the text outline effect. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the width of the text outline effect. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1607,6 +1870,11 @@ class ElementComponent extends Component { this._setValue('outlineThickness', arg); } + /** + * Gets the width of the text outline effect. + * + * @type {number} + */ get outlineThickness() { if (this._text) { return this._text.outlineThickness; @@ -1616,7 +1884,7 @@ class ElementComponent extends Component { } /** - * The text shadow effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the text shadow effect color and opacity. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {import('../../../core/math/color.js').Color} */ @@ -1624,6 +1892,11 @@ class ElementComponent extends Component { this._setValue('shadowColor', arg); } + /** + * Gets the text shadow effect color and opacity. + * + * @type {import('../../../core/math/color.js').Color} + */ get shadowColor() { if (this._text) { return this._text.shadowColor; @@ -1633,7 +1906,7 @@ class ElementComponent extends Component { } /** - * The text shadow effect shift amount from original text. Only works for + * Sets the text shadow effect shift amount from original text. Only works for * {@link ELEMENTTYPE_TEXT} types. * * @type {number} @@ -1642,6 +1915,11 @@ class ElementComponent extends Component { this._setValue('shadowOffset', arg); } + /** + * Gets the text shadow effect shift amount from original text. + * + * @type {number} + */ get shadowOffset() { if (this._text) { return this._text.shadowOffset; @@ -1651,8 +1929,8 @@ class ElementComponent extends Component { } /** - * Flag for enabling markup processing. Only works for {@link ELEMENTTYPE_TEXT} types. Defaults - * to false. + * Sets whether markup processing is enabled for this element. Only works for + * {@link ELEMENTTYPE_TEXT} types. Defaults to false. * * @type {boolean} */ @@ -1660,6 +1938,11 @@ class ElementComponent extends Component { this._setValue('enableMarkup', arg); } + /** + * Gets whether markup processing is enabled for this element. + * + * @type {boolean} + */ get enableMarkup() { if (this._text) { return this._text.enableMarkup; @@ -1669,7 +1952,7 @@ class ElementComponent extends Component { } /** - * Index of the first character to render. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the index of the first character to render. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1677,6 +1960,11 @@ class ElementComponent extends Component { this._setValue('rangeStart', arg); } + /** + * Gets the index of the first character to render. + * + * @type {number} + */ get rangeStart() { if (this._text) { return this._text.rangeStart; @@ -1686,7 +1974,7 @@ class ElementComponent extends Component { } /** - * Index of the last character to render. Only works for {@link ELEMENTTYPE_TEXT} types. + * Sets the index of the last character to render. Only works for {@link ELEMENTTYPE_TEXT} types. * * @type {number} */ @@ -1694,6 +1982,11 @@ class ElementComponent extends Component { this._setValue('rangeEnd', arg); } + /** + * Gets the index of the last character to render. + * + * @type {number} + */ get rangeEnd() { if (this._text) { return this._text.rangeEnd; diff --git a/src/framework/components/gsplat/component.js b/src/framework/components/gsplat/component.js index 785beac33a4..818ff1053da 100644 --- a/src/framework/components/gsplat/component.js +++ b/src/framework/components/gsplat/component.js @@ -69,10 +69,9 @@ class GSplatComponent extends Component { } /** - * If set, the object space bounding box is used as a bounding box for visibility culling of - * attached gsplat. This allows a custom bounding box to be specified. + * Sets a custom object space bounding box for visibility culling of the attached gsplat. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox} + * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} */ set customAabb(value) { this._customAabb = value; @@ -81,13 +80,19 @@ class GSplatComponent extends Component { this._instance?.meshInstance?.setCustomAabb(this._customAabb); } + /** + * Gets the custom object space bounding box for visibility culling of the attached gsplat. + * + * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + */ get customAabb() { return this._customAabb; } /** - * A {@link GSplatInstance} contained in the component. If not set or loaded, it returns null. + * Sets a {@link GSplatInstance} on the component. If not set or loaded, it returns null. * + * @type {import('../../../scene/gsplat/gsplat-instance.js').GSplatInstance|null} * @ignore */ set instance(value) { @@ -118,6 +123,12 @@ class GSplatComponent extends Component { } } + /** + * Gets the {@link GSplatInstance} on the component. + * + * @type {import('../../../scene/gsplat/gsplat-instance.js').GSplatInstance|null} + * @ignore + */ get instance() { return this._instance; } @@ -136,7 +147,7 @@ class GSplatComponent extends Component { } /** - * Material used to render the gsplat. + * Gets the material used to render the gsplat. * * @type {import('../../../scene/materials/material.js').Material|undefined} */ @@ -145,8 +156,8 @@ class GSplatComponent extends Component { } /** - * An array of layer IDs ({@link Layer#id}) to which gsplats should belong. Don't push, pop, - * splice or modify this array, if you want to change it - set a new one instead. + * Sets an array of layer IDs ({@link Layer#id}) to which this gsplat should belong. Don't + * push, pop, splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -169,12 +180,17 @@ class GSplatComponent extends Component { this.addToLayers(); } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this gsplat belongs. + * + * @type {number[]} + */ get layers() { return this._layers; } /** - * The gsplat asset for the gsplat component - can also be an asset id. + * Sets the gsplat asset for this gsplat component. Can also be an asset id. * * @type {Asset|number} */ @@ -194,6 +210,11 @@ class GSplatComponent extends Component { } } + /** + * Gets the gsplat asset id for this gsplat component. + * + * @type {Asset|number} + */ get asset() { return this._assetReference.id; } diff --git a/src/framework/components/layout-child/component.js b/src/framework/components/layout-child/component.js index 100e487e51b..87435571054 100644 --- a/src/framework/components/layout-child/component.js +++ b/src/framework/components/layout-child/component.js @@ -35,7 +35,7 @@ class LayoutChildComponent extends Component { } /** - * The minimum width the element should be rendered at. + * Sets the minimum width the element should be rendered at. * * @type {number} */ @@ -46,12 +46,17 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the minimum width the element should be rendered at. + * + * @type {number} + */ get minWidth() { return this._minWidth; } /** - * The minimum height the element should be rendered at. + * Sets the minimum height the element should be rendered at. * * @type {number} */ @@ -62,12 +67,17 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the minimum height the element should be rendered at. + * + * @type {number} + */ get minHeight() { return this._minHeight; } /** - * The maximum width the element should be rendered at. + * Sets the maximum width the element should be rendered at. * * @type {number|null} */ @@ -78,12 +88,17 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the maximum width the element should be rendered at. + * + * @type {number|null} + */ get maxWidth() { return this._maxWidth; } /** - * The maximum height the element should be rendered at. + * Sets the maximum height the element should be rendered at. * * @type {number|null} */ @@ -94,12 +109,17 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the maximum height the element should be rendered at. + * + * @type {number|null} + */ get maxHeight() { return this._maxHeight; } /** - * The amount of additional horizontal space that the element should take up, if necessary to + * Sets the amount of additional horizontal space that the element should take up, if necessary to * satisfy a Stretch/Shrink fitting calculation. This is specified as a proportion, taking into * account the proportion values of other siblings. * @@ -112,12 +132,18 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the amount of additional horizontal space that the element should take up, if necessary to + * satisfy a Stretch/Shrink fitting calculation. + * + * @type {number} + */ get fitWidthProportion() { return this._fitWidthProportion; } /** - * The amount of additional vertical space that the element should take up, if necessary to + * Sets the amount of additional vertical space that the element should take up, if necessary to * satisfy a Stretch/Shrink fitting calculation. This is specified as a proportion, taking into * account the proportion values of other siblings. * @@ -130,12 +156,18 @@ class LayoutChildComponent extends Component { } } + /** + * Gets the amount of additional vertical space that the element should take up, if necessary to + * satisfy a Stretch/Shrink fitting calculation. + * + * @type {number} + */ get fitHeightProportion() { return this._fitHeightProportion; } /** - * If set to true, the child will be excluded from all layout calculations. + * Sets whether the child will be excluded from all layout calculations. * * @type {boolean} */ @@ -146,6 +178,11 @@ class LayoutChildComponent extends Component { } } + /** + * Gets whether the child will be excluded from all layout calculations. + * + * @type {boolean} + */ get excludeFromLayout() { return this._excludeFromLayout; } diff --git a/src/framework/components/layout-group/component.js b/src/framework/components/layout-group/component.js index bd5745d51d0..f2cc6a67c3b 100644 --- a/src/framework/components/layout-group/component.js +++ b/src/framework/components/layout-group/component.js @@ -80,7 +80,7 @@ class LayoutGroupComponent extends Component { } /** - * Whether the layout should run horizontally or vertically. Can be: + * Sets whether the layout should run horizontally or vertically. Can be: * * - {@link ORIENTATION_HORIZONTAL} * - {@link ORIENTATION_VERTICAL} @@ -96,12 +96,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets whether the layout should run horizontally or vertically. + * + * @type {number} + */ get orientation() { return this._orientation; } /** - * Reverses the order of children along the x axis. Defaults to false. + * Sets whether to reverse the order of children along the x axis. Defaults to false. * * @type {boolean} */ @@ -112,12 +117,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets whether to reverse the order of children along the x axis. + * + * @type {boolean} + */ get reverseX() { return this._reverseX; } /** - * Reverses the order of children along the y axis. Defaults to true. + * Sets whether to reverse the order of children along the y axis. Defaults to true. * * @type {boolean} */ @@ -128,13 +138,18 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets whether to reverse the order of children along the y axis. + * + * @type {boolean} + */ get reverseY() { return this._reverseY; } /** - * Specifies the horizontal and vertical alignment of child elements. Values range from 0 to 1 - * where [0, 0] is the bottom left and [1, 1] is the top right. Defaults to [0, 1]. + * Sets the horizontal and vertical alignment of child elements. Values range from 0 to 1 where + * `[0, 0]` is the bottom left and `[1, 1]` is the top right. Defaults to `[0, 1]`. * * @type {Vec2} */ @@ -145,13 +160,18 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets the horizontal and vertical alignment of child elements. + * + * @type {Vec2} + */ get alignment() { return this._alignment; } /** - * Padding to be applied inside the container before positioning any children. Specified as - * left, bottom, right and top values. Defaults to [0, 0, 0, 0] (no padding). + * Sets the padding to be applied inside the container before positioning any children. + * Specified as left, bottom, right and top values. Defaults to `[0, 0, 0, 0]` (no padding). * * @type {Vec4} */ @@ -162,12 +182,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets the padding to be applied inside the container before positioning any children. + * + * @type {Vec4} + */ get padding() { return this._padding; } /** - * Spacing to be applied between each child element. Defaults to [0, 0] (no spacing). + * Sets the spacing to be applied between each child element. Defaults to `[0, 0]` (no spacing). * * @type {Vec2} */ @@ -178,12 +203,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets the spacing to be applied between each child element. + * + * @type {Vec2} + */ get spacing() { return this._spacing; } /** - * Fitting logic to be applied when positioning and scaling child elements. Can be: + * Sets the width fitting mode to be applied when positioning and scaling child elements. Can be: * * - {@link FITTING_NONE}: Child elements will be rendered at their natural size. * - {@link FITTING_STRETCH}: When the natural size of all child elements does not fill the width @@ -218,11 +248,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets the width fitting mode to be applied when positioning and scaling child elements. + * + * @type {number} + */ get widthFitting() { return this._widthFitting; } /** + * Sets the height fitting mode to be applied when positioning and scaling child elements. * Identical to {@link LayoutGroupComponent#widthFitting} but for the Y axis. Defaults to * {@link FITTING_NONE}. * @@ -235,12 +271,17 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets the height fitting mode to be applied when positioning and scaling child elements. + * + * @type {number} + */ get heightFitting() { return this._heightFitting; } /** - * Whether or not to wrap children onto a new row/column when the size of the container is + * Sets whether or not to wrap children onto a new row/column when the size of the container is * exceeded. Defaults to false, which means that children will be be rendered in a single row * (horizontal orientation) or column (vertical orientation). Note that setting wrap to true * makes it impossible for the {@link FITTING_BOTH} fitting mode to operate in any logical @@ -257,6 +298,12 @@ class LayoutGroupComponent extends Component { } } + /** + * Gets whether or not to wrap children onto a new row/column when the size of the container is + * exceeded. + * + * @type {boolean} + */ get wrap() { return this._wrap; } diff --git a/src/framework/components/light/component.js b/src/framework/components/light/component.js index 5475a256d04..99fbb6e9f16 100644 --- a/src/framework/components/light/component.js +++ b/src/framework/components/light/component.js @@ -64,6 +64,8 @@ class LightComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { @@ -72,6 +74,11 @@ class LightComponent extends Component { }); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } @@ -84,17 +91,22 @@ class LightComponent extends Component { this._setValue('light', arg); } + /** + * @type {import('../../../scene/light.js').Light} + * @ignore + */ get light() { return this.data.light; } /** - * The type of light. Can be: + * Sets the type of the light. Can be: * * - "directional": A light that is infinitely far away and lights the entire scene from one * direction. * - "omni": An omni-directional light that illuminates in all directions from the light source. * - "spot": An omni-directional light but is bounded by a cone. + * * Defaults to "directional". * * @type {string} @@ -106,13 +118,18 @@ class LightComponent extends Component { }); } + /** + * Gets the type of the light. + * + * @type {string} + */ get type() { return this.data.type; } /** - * The Color of the light. The alpha component of the color is ignored. - * Defaults to white (1, 1, 1). + * Sets the color of the light. The alpha component of the color is ignored. Defaults to white + * (`[1, 1, 1]`). * * @type {import('../../../core/math/color.js').Color}; */ @@ -127,12 +144,17 @@ class LightComponent extends Component { ); } + /** + * Gets the color of the light. + * + * @type {import('../../../core/math/color.js').Color}; + */ get color() { return this.data.color; } /** - * The brightness of the light. Defaults to 1. + * Sets the brightness of the light. Defaults to 1. * * @type {number} */ @@ -142,12 +164,17 @@ class LightComponent extends Component { }); } + /** + * Gets the brightness of the light. + * + * @type {number} + */ get intensity() { return this.data.intensity; } /** - * The physically based luminance. Only used if scene.physicalUnits is true. Defaults to 0. + * Sets the physically-based luminance. Only used if `scene.physicalUnits` is true. Defaults to 0. * * @type {number} */ @@ -157,12 +184,17 @@ class LightComponent extends Component { }); } + /** + * Gets the physically-based luminance. + * + * @type {number} + */ get luminance() { return this.data.luminance; } /** - * The light source shape. Can be: + * Sets the light source shape. Can be: * * - {@link LIGHTSHAPE_PUNCTUAL}: Infinitesimally small point. * - {@link LIGHTSHAPE_RECT}: Rectangle shape. @@ -179,13 +211,18 @@ class LightComponent extends Component { }); } + /** + * Gets the light source shape. + * + * @type {number} + */ get shape() { return this.data.shape; } /** - * If enabled, material specularity will be affected by this light. - * Ignored for lights other than {@link LIGHTTYPE_DIRECTIONAL}. Defaults to true. + * Sets whether material specularity will be affected by this light. Ignored for lights other + * than {@link LIGHTTYPE_DIRECTIONAL}. Defaults to true. * * @type {boolean} */ @@ -195,12 +232,17 @@ class LightComponent extends Component { }); } + /** + * Gets whether material specularity will be affected by this light. + * + * @type {boolean} + */ get affectSpecularity() { return this.data.affectSpecularity; } /** - * If enabled the light will cast shadows. Defaults to false. + * Sets whether the light will cast shadows. Defaults to false. * * @type {boolean} */ @@ -210,13 +252,18 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light will cast shadows. + * + * @type {boolean} + */ get castShadows() { return this.data.castShadows; } /** - * The distance from the viewpoint beyond which shadows are no - * longer rendered. Affects directional lights only. Defaults to 40. + * Sets the distance from the viewpoint beyond which shadows are no longer rendered. Affects + * directional lights only. Defaults to 40. * * @type {number} */ @@ -226,13 +273,18 @@ class LightComponent extends Component { }); } + /** + * Gets the distance from the viewpoint beyond which shadows are no longer rendered. + * + * @type {number} + */ get shadowDistance() { return this.data.shadowDistance; } /** - * The intensity of the shadow darkening, 1 being shadows are entirely black. - * Defaults to 1. + * Sets the intensity of the shadow darkening. 0 having no effect and 1 meaning shadows are + * entirely black. Defaults to 1. * * @type {number} */ @@ -242,13 +294,18 @@ class LightComponent extends Component { }); } + /** + * Gets the intensity of the shadow darkening. + * + * @type {number} + */ get shadowIntensity() { return this.data.shadowIntensity; } /** - * The size of the texture used for the shadow map. Valid sizes - * are 64, 128, 256, 512, 1024, 2048. Defaults to 1024. + * Sets the size of the texture used for the shadow map. Valid sizes are 64, 128, 256, 512, + * 1024, 2048. Defaults to 1024. * * @type {number} */ @@ -258,12 +315,17 @@ class LightComponent extends Component { }); } + /** + * Gets the size of the texture used for the shadow map. + * + * @type {number} + */ get shadowResolution() { return this.data.shadowResolution; } /** - * The depth bias for tuning the appearance of the shadow mapping generated by this light. Valid + * Set the depth bias for tuning the appearance of the shadow mapping generated by this light. Valid * range is 0 to 1. Defaults to 0.05. * * @type {number} @@ -274,13 +336,18 @@ class LightComponent extends Component { }); } + /** + * Get the depth bias for tuning the appearance of the shadow mapping generated by this light. + * + * @type {number} + */ get shadowBias() { return this.data.shadowBias; } /** - * Number of shadow cascades. Can be 1, 2, 3 or 4. Defaults to 1, - * representing no cascades. + * Sets the number of shadow cascades. Can be 1, 2, 3 or 4. Defaults to 1, representing no + * cascades. * * @type {number} */ @@ -290,13 +357,18 @@ class LightComponent extends Component { }); } + /** + * Gets the number of shadow cascades. + * + * @type {number} + */ get numCascades() { return this.data.numCascades; } /** - * If bake is true, this specifies the number of samples used to - * bake this light into the lightmap. Defaults to 1. Maximum value is 255. + * Sets the number of samples used to bake this light into the lightmap. Defaults to 1. Maximum + * value is 255. * * @type {number} */ @@ -306,13 +378,18 @@ class LightComponent extends Component { }); } + /** + * Gets the number of samples used to bake this light into the lightmap. + * + * @type {number} + */ get bakeNumSamples() { return this.data.bakeNumSamples; } /** - * If bake is true and the light type is {@link LIGHTTYPE_DIRECTIONAL}, - * this specifies the penumbra angle in degrees, allowing a soft shadow boundary. Defaults to 0. + * Sets the penumbra angle in degrees, allowing for a soft shadow boundary. Defaults to 0. + * Requires `bake` to be set to true and the light type is {@link LIGHTTYPE_DIRECTIONAL}. * * @type {number} */ @@ -322,16 +399,21 @@ class LightComponent extends Component { }); } + /** + * Gets the penumbra angle in degrees. + * + * @type {number} + */ get bakeArea() { return this.data.bakeArea; } /** - * The distribution of subdivision of the camera frustum for individual shadow cascades. - * Only used if {@link LightComponent#numCascades} is larger than 1. - * Can be a value in range of 0 and 1. Value of 0 represents a linear distribution, value of 1 - * represents a logarithmic distribution. Defaults to 0.5. Larger value increases the resolution of - * the shadows in the near distance. + * Sets the distribution of subdivision of the camera frustum for individual shadow cascades. + * Only used if {@link LightComponent#numCascades} is larger than 1. Can be a value in range of + * 0 and 1. Value of 0 represents a linear distribution, value of 1 represents a logarithmic + * distribution. Defaults to 0.5. Larger value increases the resolution of the shadows in the + * near distance. * * @type {number} */ @@ -341,12 +423,17 @@ class LightComponent extends Component { }); } + /** + * Gets the distribution of subdivision of the camera frustum for individual shadow cascades. + * + * @type {number} + */ get cascadeDistribution() { return this.data.cascadeDistribution; } /** - * Normal offset depth bias. Valid range is 0 to 1. Defaults to 0. + * Sets the normal offset depth bias. Valid range is 0 to 1. Defaults to 0. * * @type {number} */ @@ -356,12 +443,17 @@ class LightComponent extends Component { }); } + /** + * Gets the normal offset depth bias. + * + * @type {number} + */ get normalOffsetBias() { return this.data.normalOffsetBias; } /** - * The range of the light. Affects omni and spot lights only. Defaults to 10. + * Sets the range of the light. Affects omni and spot lights only. Defaults to 10. * * @type {number} */ @@ -371,13 +463,18 @@ class LightComponent extends Component { }); } + /** + * Gets the range of the light. + * + * @type {number} + */ get range() { return this.data.range; } /** - * The angle at which the spotlight cone starts to fade off. The - * angle is specified in degrees. Affects spot lights only. Defaults to 40. + * Sets the angle at which the spotlight cone starts to fade off. The angle is specified in + * degrees. Affects spot lights only. Defaults to 40. * * @type {number} */ @@ -387,13 +484,18 @@ class LightComponent extends Component { }); } + /** + * Gets the angle at which the spotlight cone starts to fade off. + * + * @type {number} + */ get innerConeAngle() { return this.data.innerConeAngle; } /** - * The angle at which the spotlight cone has faded to nothing. - * The angle is specified in degrees. Affects spot lights only. Defaults to 45. + * Sets the angle at which the spotlight cone has faded to nothing. The angle is specified in + * degrees. Affects spot lights only. Defaults to 45. * * @type {number} */ @@ -403,12 +505,18 @@ class LightComponent extends Component { }); } + /** + * Gets the angle at which the spotlight cone has faded to nothing. + * + * @type {number} + */ get outerConeAngle() { return this.data.outerConeAngle; } /** - * Controls the rate at which a light attenuates from its position. Can be: + * Sets the fall off mode for the light. This controls the rate at which a light attenuates + * from its position. Can be: * * - {@link LIGHTFALLOFF_LINEAR}: Linear. * - {@link LIGHTFALLOFF_INVERSESQUARED}: Inverse squared. @@ -423,12 +531,17 @@ class LightComponent extends Component { }); } + /** + * Gets the fall off mode for the light. + * + * @type {number} + */ get falloffMode() { return this.data.falloffMode; } /** - * Type of shadows being rendered by this light. Options: + * Sets the type of shadows being rendered by this light. Can be: * * - {@link SHADOW_PCF3}: Render depth (color-packed on WebGL 1.0), can be used for PCF 3x3 * sampling. @@ -450,13 +563,18 @@ class LightComponent extends Component { }); } + /** + * Gets the type of shadows being rendered by this light. + * + * @type {number} + */ get shadowType() { return this.data.shadowType; } /** - * Number of samples used for blurring a variance shadow map. Only uneven numbers work, - * even are incremented. Minimum value is 1, maximum is 25. Defaults to 11. + * Sets the number of samples used for blurring a variance shadow map. Only uneven numbers + * work, even are incremented. Minimum value is 1, maximum is 25. Defaults to 11. * * @type {number} */ @@ -466,12 +584,17 @@ class LightComponent extends Component { }); } + /** + * Gets the number of samples used for blurring a variance shadow map. + * + * @type {number} + */ get vsmBlurSize() { return this.data.vsmBlurSize; } /** - * Blurring mode for variance shadow maps. Can be: + * Sets the blurring mode for variance shadow maps. Can be: * * - {@link BLUR_BOX}: Box filter. * - {@link BLUR_GAUSSIAN}: Gaussian filter. May look smoother than box, but requires more samples. @@ -484,12 +607,17 @@ class LightComponent extends Component { }); } + /** + * Gets the blurring mode for variance shadow maps. + * + * @type {number} + */ get vsmBlurMode() { return this.data.vsmBlurMode; } /** - * TODO: + * Sets the VSM bias value. * * @type {number} */ @@ -499,13 +627,18 @@ class LightComponent extends Component { }); } + /** + * Gets the VSM bias value. + * + * @type {number} + */ get vsmBias() { return this.data.vsmBias; } /** - * Asset that has texture that will be assigned to cookie internally - * once asset resource is available. + * Sets the texture asset to be used as the cookie for this light. Only spot and omni lights can + * have cookies. Defaults to null. * * @type {number|null} */ @@ -535,13 +668,18 @@ class LightComponent extends Component { }); } + /** + * Gets the texture asset to be used as the cookie for this light. + * + * @type {number|null} + */ get cookieAsset() { return this.data.cookieAsset; } /** - * Projection texture. Must be 2D for spot and cubemap for omni light - * (ignored if incorrect type is used). + * Sets the texture to be used as the cookie for this light. Only spot and omni lights can have + * cookies. Defaults to null. * * @type {import('../../../platform/graphics/texture.js').Texture|null} */ @@ -551,12 +689,17 @@ class LightComponent extends Component { }); } + /** + * Gets the texture to be used as the cookie for this light. + * + * @type {import('../../../platform/graphics/texture.js').Texture|null} + */ get cookie() { return this.data.cookie; } /** - * Projection texture intensity (default is 1). + * Sets the cookie texture intensity. Defaults to 1. * * @type {number} */ @@ -566,14 +709,19 @@ class LightComponent extends Component { }); } + /** + * Gets the cookie texture intensity. + * + * @type {number} + */ get cookieIntensity() { return this.data.cookieIntensity; } /** - * Toggle normal spotlight falloff when projection texture is used. When set to false, - * spotlight will work like a pure texture projector (only fading with - * distance). Default is false. + * Sets whether normal spotlight falloff is active when a cookie texture is set. When set to + * false, a spotlight will work like a pure texture projector (only fading with distance). + * Default is false. * * @type {boolean} */ @@ -583,12 +731,17 @@ class LightComponent extends Component { }); } + /** + * Gets whether normal spotlight falloff is active when a cookie texture is set. + * + * @type {boolean} + */ get cookieFalloff() { return this.data.cookieFalloff; } /** - * Color channels of the projection texture to use. Can be "r", "g", "b", "a", "rgb". + * Sets the color channels of the cookie texture to use. Can be "r", "g", "b", "a", "rgb". * * @type {string} */ @@ -598,12 +751,17 @@ class LightComponent extends Component { }); } + /** + * Gets the color channels of the cookie texture to use. + * + * @type {string} + */ get cookieChannel() { return this.data.cookieChannel; } /** - * Angle for spotlight cookie rotation. + * Sets the angle for spotlight cookie rotation (in degrees). * * @type {number} */ @@ -627,12 +785,17 @@ class LightComponent extends Component { }); } + /** + * Gets the angle for spotlight cookie rotation (in degrees). + * + * @type {number} + */ get cookieAngle() { return this.data.cookieAngle; } /** - * Spotlight cookie scale. + * Sets the spotlight cookie scale. * * @type {import('../../../core/math/vec2.js').Vec2|null} */ @@ -657,14 +820,19 @@ class LightComponent extends Component { ); } + /** + * Gets the spotlight cookie scale. + * + * @type {import('../../../core/math/vec2.js').Vec2|null} + */ get cookieScale() { return this.data.cookieScale; } /** - * Spotlight cookie position offset. + * Sets the spotlight cookie position offset. * - * @type {import('../../../core/math/vec2.js').Vec2} + * @type {import('../../../core/math/vec2.js').Vec2|null} */ set cookieOffset(arg) { this._setValue( @@ -677,12 +845,17 @@ class LightComponent extends Component { ); } + /** + * Gets the spotlight cookie position offset. + * + * @type {import('../../../core/math/vec2.js').Vec2|null} + */ get cookieOffset() { return this.data.cookieOffset; } /** - * Tells the renderer how often shadows must be updated for + * Sets the shadow update model. This tells the renderer how often shadows must be updated for * this light. Can be: * * - {@link SHADOWUPDATE_NONE}: Don't render shadows. @@ -703,13 +876,17 @@ class LightComponent extends Component { ); } + /** + * Gets the shadow update model. + * + * @type {number} + */ get shadowUpdateMode() { return this.data.shadowUpdateMode; } /** - * Defines a mask to determine which {@link MeshInstance}s are lit by this - * light. Defaults to 1. + * Sets the mask to determine which {@link MeshInstance}s are lit by this light. Defaults to 1. * * @type {number} */ @@ -719,12 +896,17 @@ class LightComponent extends Component { }); } + /** + * Gets the mask to determine which {@link MeshInstance}s are lit by this light. + * + * @type {number} + */ get mask() { return this.data.mask; } /** - * If enabled the light will affect non-lightmapped objects. + * Sets whether the light will affect non-lightmapped objects. * * @type {boolean} */ @@ -739,12 +921,17 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light will affect non-lightmapped objects. + * + * @type {boolean} + */ get affectDynamic() { return this.data.affectDynamic; } /** - * If enabled the light will affect lightmapped objects. + * Sets whether the light will affect lightmapped objects. * * @type {boolean} */ @@ -760,12 +947,17 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light will affect lightmapped objects. + * + * @type {boolean} + */ get affectLightmapped() { return this.data.affectLightmapped; } /** - * If enabled the light will be rendered into lightmaps. + * Sets whether the light will be rendered into lightmaps. * * @type {boolean} */ @@ -782,16 +974,21 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light will be rendered into lightmaps. + * + * @type {boolean} + */ get bake() { return this.data.bake; } /** - * If enabled and bake=true, the light's direction will contribute to - * directional lightmaps. Be aware, that directional lightmap is an approximation and can only hold - * single direction per pixel. Intersecting multiple lights with bakeDir=true may lead to incorrect - * look of specular/bump-mapping in the area of intersection. The error is not always visible - * though, and highly scene-dependent. + * Sets whether the light's direction will contribute to directional lightmaps. The light must + * be enabled and `bake` set to true. Be aware, that directional lightmap is an approximation + * and can only hold single direction per pixel. Intersecting multiple lights with bakeDir=true + * may lead to incorrect look of specular/bump-mapping in the area of intersection. The error + * is not always visible though, and highly scene-dependent. * * @type {boolean} */ @@ -801,12 +998,17 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light's direction will contribute to directional lightmaps. + * + * @type {boolean} + */ get bakeDir() { return this.data.bakeDir; } /** - * Mark light as non-movable (optimization). + * Sets whether the light ever moves. This is an optimization hint. * * @type {boolean} */ @@ -816,14 +1018,18 @@ class LightComponent extends Component { }); } + /** + * Gets whether the light ever moves. + * + * @type {boolean} + */ get isStatic() { return this.data.isStatic; } /** - * An array of layer IDs ({@link Layer#id}) to which this light should - * belong. Don't push/pop/splice or modify this array, if you want to change it - set a new one - * instead. + * Sets the array of layer IDs ({@link Layer#id}) to which this light should belong. Don't + * push/pop/splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -846,12 +1052,17 @@ class LightComponent extends Component { }); } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this light should belong. + * + * @type {number[]} + */ get layers() { return this.data.layers; } /** - * Returns an array of SHADOWUPDATE_ settings per shadow cascade, or undefined if not used. + * Sets an array of SHADOWUPDATE_ settings per shadow cascade. Set to undefined if not used. * * @type {number[] | null} */ @@ -859,14 +1070,19 @@ class LightComponent extends Component { this.light.shadowUpdateOverrides = values; } + /** + * Gets an array of SHADOWUPDATE_ settings per shadow cascade. + * + * @type {number[] | null} + */ get shadowUpdateOverrides() { return this.light.shadowUpdateOverrides; } /** - * Size of penumbra for contact hardening shadows. For area lights acts as a multiplier with - * the dimensions of the area light. For punctual and directional lights - * it's the area size of the light. Defaults to 1.0. + * Sets the size of penumbra for contact hardening shadows. For area lights, acts as a + * multiplier with the dimensions of the area light. For punctual and directional lights it's + * the area size of the light. Defaults to 1. * * @type {number} */ @@ -874,6 +1090,11 @@ class LightComponent extends Component { this.light.penumbraSize = value; } + /** + * Gets the size of penumbra for contact hardening shadows. + * + * @type {number} + */ get penumbraSize() { return this.light.penumbraSize; } diff --git a/src/framework/components/model/component.js b/src/framework/components/model/component.js index afcbd904bd3..c455734f79e 100644 --- a/src/framework/components/model/component.js +++ b/src/framework/components/model/component.js @@ -145,8 +145,7 @@ class ModelComponent extends Component { } /** - * An array of meshInstances contained in the component's model. If model is not set or loaded - * for component it will return null. + * Sets the array of mesh instances contained in the component's model. * * @type {MeshInstance[]|null} */ @@ -157,6 +156,11 @@ class ModelComponent extends Component { this._model.meshInstances = value; } + /** + * Gets the array of mesh instances contained in the component's model. + * + * @type {MeshInstance[]|null} + */ get meshInstances() { if (!this._model) return null; @@ -165,10 +169,10 @@ class ModelComponent extends Component { } /** - * If set, the object space bounding box is used as a bounding box for visibility culling of - * attached mesh instances. This is an optimization, allowing oversized bounding box to be - * specified for skinned characters in order to avoid per frame bounding box computations based - * on bone positions. + * Sets the custom object space bounding box that is used for visibility culling of attached + * mesh instances. This is an optimization, allowing an oversized bounding box to be specified + * for skinned characters in order to avoid per frame bounding box computations based on bone + * positions. * * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} */ @@ -186,12 +190,18 @@ class ModelComponent extends Component { } } + /** + * Gets the custom object space bounding box that is used for visibility culling of attached + * mesh instances. + * + * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + */ get customAabb() { return this._customAabb; } /** - * The type of the model. Can be: + * Sets the type of the component. Can be one of the following: * * - "asset": The component will render a model asset * - "box": The component will render a box (1 unit in each dimension) @@ -235,12 +245,18 @@ class ModelComponent extends Component { } } + /** + * Gets the type of the component. + * + * @type {string} + */ get type() { return this._type; } /** - * The asset for the model (only applies to models of type 'asset') can also be an asset id. + * Sets the model asset (or asset id) for the component. This only applies to model components + * with type 'asset'. * * @type {Asset|number|null} */ @@ -278,12 +294,17 @@ class ModelComponent extends Component { } } + /** + * Gets the model asset id for the component. + * + * @type {Asset|number|null} + */ get asset() { return this._asset; } /** - * The model that is added to the scene graph. It can be not set or loaded, so will return null. + * Sets the model owned by this component. * * @type {Model} */ @@ -353,12 +374,19 @@ class ModelComponent extends Component { } } + /** + * Gets the model owned by this component. In this case a model is not set or loaded, this will + * return null. + * + * @type {Model} + */ get model() { return this._model; } /** - * If true, this model will be lightmapped after using lightmapper.bake(). + * Sets whether the component is affected by the runtime lightmapper. If true, the meshes will + * be lightmapped after using lightmapper.bake(). * * @type {boolean} */ @@ -376,12 +404,17 @@ class ModelComponent extends Component { } } + /** + * Gets whether the component is affected by the runtime lightmapper. + * + * @type {boolean} + */ get lightmapped() { return this._lightmapped; } /** - * If true, this model will cast shadows for lights that have shadow casting enabled. + * Sets whether attached meshes will cast shadows for lights that have shadow casting enabled. * * @type {boolean} */ @@ -418,12 +451,17 @@ class ModelComponent extends Component { this._castShadows = value; } + /** + * Gets whether attached meshes will cast shadows for lights that have shadow casting enabled. + * + * @type {boolean} + */ get castShadows() { return this._castShadows; } /** - * If true, shadows will be cast on this model. + * Sets whether shadows will be cast on attached meshes. * * @type {boolean} */ @@ -440,12 +478,17 @@ class ModelComponent extends Component { } } + /** + * Gets whether shadows will be cast on attached meshes. + * + * @type {boolean} + */ get receiveShadows() { return this._receiveShadows; } /** - * If true, this model will cast shadows when rendering lightmaps. + * Sets whether meshes instances will cast shadows when rendering lightmaps. * * @type {boolean} */ @@ -453,12 +496,17 @@ class ModelComponent extends Component { this._castShadowsLightmap = value; } + /** + * Gets whether meshes instances will cast shadows when rendering lightmaps. + * + * @type {boolean} + */ get castShadowsLightmap() { return this._castShadowsLightmap; } /** - * Lightmap resolution multiplier. + * Sets the lightmap resolution multiplier. * * @type {number} */ @@ -466,13 +514,18 @@ class ModelComponent extends Component { this._lightmapSizeMultiplier = value; } + /** + * Gets the lightmap resolution multiplier. + * + * @type {number} + */ get lightmapSizeMultiplier() { return this._lightmapSizeMultiplier; } /** - * An array of layer IDs ({@link Layer#id}) to which this model should belong. Don't push, pop, - * splice or modify this array, if you want to change it - set a new one instead. + * Sets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong. Don't + * push, pop, splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -505,12 +558,18 @@ class ModelComponent extends Component { } } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong. + * + * @type {number[]} + */ get layers() { return this._layers; } /** - * Assign model to a specific batch group (see {@link BatchGroup}). Default is -1 (no group). + * Sets the batch group for the mesh instances in this component (see {@link BatchGroup}). + * Default is -1 (no group). * * @type {number} */ @@ -532,13 +591,18 @@ class ModelComponent extends Component { this._batchGroupId = value; } + /** + * Gets the batch group for the mesh instances in this component (see {@link BatchGroup}). + * + * @type {number} + */ get batchGroupId() { return this._batchGroupId; } /** - * The material {@link Asset} that will be used to render the model (not used on models of type - * 'asset'). + * Sets the material {@link Asset} that will be used to render the component. The material is + * ignored for renders of type 'asset'. * * @type {Asset|number|null} */ @@ -575,13 +639,18 @@ class ModelComponent extends Component { } } + /** + * Gets the material {@link Asset} that will be used to render the component. + * + * @type {Asset|number|null} + */ get materialAsset() { return this._materialAsset; } /** - * The material {@link Material} that will be used to render the model (not used on models of - * type 'asset'). + * Sets the {@link Material} that will be used to render the model. The material is ignored for + * renders of type 'asset'. * * @type {import('../../../scene/materials/material.js').Material} */ @@ -594,14 +663,19 @@ class ModelComponent extends Component { this._setMaterial(value); } + /** + * Gets the {@link Material} that will be used to render the model. + * + * @type {import('../../../scene/materials/material.js').Material} + */ get material() { return this._material; } /** - * A dictionary that holds material overrides for each mesh instance. Only applies to model - * components of type 'asset'. The mapping contains pairs of mesh instance index - material - * asset id. + * Sets the dictionary that holds material overrides for each mesh instance. Only applies to + * model components of type 'asset'. The mapping contains pairs of mesh instance index to + * material asset id. * * @type {Object} */ @@ -651,6 +725,11 @@ class ModelComponent extends Component { } } + /** + * Gets the dictionary that holds material overrides for each mesh instance. + * + * @type {Object} + */ get mapping() { return this._mapping; } diff --git a/src/framework/components/particle-system/component.js b/src/framework/components/particle-system/component.js index cc8d54bed57..3a83a537440 100644 --- a/src/framework/components/particle-system/component.js +++ b/src/framework/components/particle-system/component.js @@ -148,20 +148,27 @@ class ParticleSystemComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { this._setValue('enabled', arg); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } /** - * Controls whether the particle system plays automatically on creation. - * If set to false, it is necessary to call {@link ParticleSystemComponent#play} for - * the particle system to play. Defaults to true. + * Sets whether the particle system plays automatically on creation. If set to false, it is + * necessary to call {@link ParticleSystemComponent#play} for the particle system to play. + * Defaults to true. * * @type {boolean} */ @@ -169,12 +176,17 @@ class ParticleSystemComponent extends Component { this._setValue('autoPlay', arg); } + /** + * Gets whether the particle system plays automatically on creation. + * + * @type {boolean} + */ get autoPlay() { return this.data.autoPlay; } /** - * Maximum number of simulated particles. + * Sets the maximum number of simulated particles. * * @type {number} */ @@ -182,12 +194,17 @@ class ParticleSystemComponent extends Component { this._setValue('numParticles', arg); } + /** + * Gets the maximum number of simulated particles. + * + * @type {number} + */ get numParticles() { return this.data.numParticles; } /** - * The length of time in seconds between a particle's birth and its death. + * Sets the length of time in seconds between a particle's birth and its death. * * @type {number} */ @@ -195,12 +212,17 @@ class ParticleSystemComponent extends Component { this._setValue('lifetime', arg); } + /** + * Gets the length of time in seconds between a particle's birth and its death. + * + * @type {number} + */ get lifetime() { return this.data.lifetime; } /** - * Minimal interval in seconds between particle births. + * Sets the minimal interval in seconds between particle births. * * @type {number} */ @@ -208,12 +230,17 @@ class ParticleSystemComponent extends Component { this._setValue('rate', arg); } + /** + * Gets the minimal interval in seconds between particle births. + * + * @type {number} + */ get rate() { return this.data.rate; } /** - * Maximal interval in seconds between particle births. + * Sets the maximal interval in seconds between particle births. * * @type {number} */ @@ -221,12 +248,17 @@ class ParticleSystemComponent extends Component { this._setValue('rate2', arg); } + /** + * Gets the maximal interval in seconds between particle births. + * + * @type {number} + */ get rate2() { return this.data.rate2; } /** - * Minimal initial Euler angle of a particle. + * Sets the minimal initial Euler angle of a particle. * * @type {number} */ @@ -234,12 +266,17 @@ class ParticleSystemComponent extends Component { this._setValue('startAngle', arg); } + /** + * Gets the minimal initial Euler angle of a particle. + * + * @type {number} + */ get startAngle() { return this.data.startAngle; } /** - * Maximal initial Euler angle of a particle. + * Sets the maximal initial Euler angle of a particle. * * @type {number} */ @@ -247,12 +284,17 @@ class ParticleSystemComponent extends Component { this._setValue('startAngle2', arg); } + /** + * Gets the maximal initial Euler angle of a particle. + * + * @type {number} + */ get startAngle2() { return this.data.startAngle2; } /** - * Enables or disables respawning of particles. + * Sets whether the particle system loops. * * @type {boolean} */ @@ -260,13 +302,18 @@ class ParticleSystemComponent extends Component { this._setValue('loop', arg); } + /** + * Gets whether the particle system loops. + * + * @type {boolean} + */ get loop() { return this.data.loop; } /** - * If enabled, the particle system will be initialized as though it had already completed a full - * cycle. This only works with looping particle systems. + * Sets whether the particle system will be initialized as though it has already completed a + * full cycle. This only works with looping particle systems. * * @type {boolean} */ @@ -274,12 +321,18 @@ class ParticleSystemComponent extends Component { this._setValue('preWarm', arg); } + /** + * Gets whether the particle system will be initialized as though it has already completed a + * full cycle. + * + * @type {boolean} + */ get preWarm() { return this.data.preWarm; } /** - * If enabled, particles will be lit by ambient and directional lights. + * Sets whether particles will be lit by ambient and directional lights. * * @type {boolean} */ @@ -287,13 +340,19 @@ class ParticleSystemComponent extends Component { this._setValue('lighting', arg); } + /** + * Gets whether particles will be lit by ambient and directional lights. + * + * @type {boolean} + */ get lighting() { return this.data.lighting; } /** - * Enabling Half Lambert lighting avoids particles looking too flat in shadowed areas. It is a - * completely non-physical lighting model but can give more pleasing visual results. + * Sets whether Half Lambert lighting is enabled. Enabling Half Lambert lighting avoids + * particles looking too flat in shadowed areas. It is a completely non-physical lighting model + * but can give more pleasing visual results. * * @type {boolean} */ @@ -301,12 +360,17 @@ class ParticleSystemComponent extends Component { this._setValue('halfLambert', arg); } + /** + * Gets whether Half Lambert lighting is enabled. + * + * @type {boolean} + */ get halfLambert() { return this.data.halfLambert; } /** - * Color multiplier. + * Sets the color multiplier. * * @type {number} */ @@ -314,14 +378,19 @@ class ParticleSystemComponent extends Component { this._setValue('intensity', arg); } + /** + * Gets the color multiplier. + * + * @type {number} + */ get intensity() { return this.data.intensity; } /** - * If enabled, the particles will write to the depth buffer. If disabled, the depth buffer is - * left unchanged and particles will be guaranteed to overwrite one another in the order in - * which they are rendered. + * Sets whether depth writes is enabled. If enabled, the particles will write to the depth + * buffer. If disabled, the depth buffer is left unchanged and particles will be guaranteed to + * overwrite one another in the order in which they are rendered. * * @type {boolean} */ @@ -329,12 +398,17 @@ class ParticleSystemComponent extends Component { this._setValue('depthWrite', arg); } + /** + * Gets whether depth writes is enabled. + * + * @type {boolean} + */ get depthWrite() { return this.data.depthWrite; } /** - * Disable fogging. + * Sets whether fogging is ignored. * * @type {boolean} */ @@ -342,15 +416,20 @@ class ParticleSystemComponent extends Component { this._setValue('noFog', arg); } + /** + * Gets whether fogging is ignored. + * + * @type {boolean} + */ get noFog() { return this.data.noFog; } /** - * Controls fading of particles near their intersections with scene geometry. This effect, when - * it's non-zero, requires scene depth map to be rendered. Multiple depth-dependent effects can - * share the same map, but if you only use it for particles, bear in mind that it can double - * engine draw calls. + * Sets whether depth softening is enabled. Controls fading of particles near their + * intersections with scene geometry. This effect, when it's non-zero, requires scene depth map + * to be rendered. Multiple depth-dependent effects can share the same map, but if you only use + * it for particles, bear in mind that it can double engine draw calls. * * @type {number} */ @@ -358,12 +437,17 @@ class ParticleSystemComponent extends Component { this._setValue('depthSoftening', arg); } + /** + * Gets whether depth softening is enabled. + * + * @type {number} + */ get depthSoftening() { return this.data.depthSoftening; } /** - * Sorting mode. Forces CPU simulation, so be careful. + * Sets the particle sorting mode. Forces CPU simulation, so be careful. * * - {@link PARTICLESORT_NONE}: No sorting, particles are drawn in arbitrary order. Can be * simulated on GPU. @@ -377,12 +461,17 @@ class ParticleSystemComponent extends Component { this._setValue('sort', arg); } + /** + * Gets the particle sorting mode. + * + * @type {number} + */ get sort() { return this.data.sort; } /** - * Controls how particles are blended when being written to the currently active render target. + * Sets how particles are blended when being written to the currently active render target. * Can be: * * - {@link BLEND_SUBTRACTIVE}: Subtract the color of the source fragment from the destination @@ -409,13 +498,19 @@ class ParticleSystemComponent extends Component { this._setValue('blendType', arg); } + /** + * Gets how particles are blended when being written to the currently active render target. + * + * @type {number} + */ get blendType() { return this.data.blendType; } /** - * A value in world units that controls the amount by which particles are stretched based on - * their velocity. Particles are stretched from their center towards their previous position. + * Sets how much particles are stretched in their direction of motion. This is a value in world + * units that controls the amount by which particles are stretched based on their velocity. + * Particles are stretched from their center towards their previous position. * * @type {number} */ @@ -423,12 +518,17 @@ class ParticleSystemComponent extends Component { this._setValue('stretch', arg); } + /** + * Gets how much particles are stretched in their direction of motion. + * + * @type {number} + */ get stretch() { return this.data.stretch; } /** - * Orient particles in their direction of motion. + * Sets whether particles are oriented in their direction of motion or not. * * @type {boolean} */ @@ -436,13 +536,18 @@ class ParticleSystemComponent extends Component { this._setValue('alignToMotion', arg); } + /** + * Gets whether particles are oriented in their direction of motion or not. + * + * @type {boolean} + */ get alignToMotion() { return this.data.alignToMotion; } /** - * Shape of the emitter. Defines the bounds inside which particles are spawned. Also affects the - * direction of initial velocity. + * Sets the shape of the emitter. Defines the bounds inside which particles are spawned. Also + * affects the direction of initial velocity. * * - {@link EMITTERSHAPE_BOX}: Box shape parameterized by emitterExtents. Initial velocity is * directed towards local Z axis. @@ -455,13 +560,18 @@ class ParticleSystemComponent extends Component { this._setValue('emitterShape', arg); } + /** + * Gets the shape of the emitter. + * + * @type {number} + */ get emitterShape() { return this.data.emitterShape; } /** - * (Only for EMITTERSHAPE_BOX) - * The extents of a local space bounding box within which particles are spawned at random positions. + * Sets the extents of a local space bounding box within which particles are spawned at random + * positions. This only applies to particle system with the shape `EMITTERSHAPE_BOX`. * * @type {import('../../../core/math/vec3.js').Vec3} */ @@ -469,14 +579,20 @@ class ParticleSystemComponent extends Component { this._setValue('emitterExtents', arg); } + /** + * Gets the extents of a local space bounding box within which particles are spawned at random + * positions. + * + * @type {import('../../../core/math/vec3.js').Vec3} + */ get emitterExtents() { return this.data.emitterExtents; } /** - * (Only for EMITTERSHAPE_BOX) - * The exception of extents of a local space bounding box within - * which particles are not spawned. Aligned to the center of EmitterExtents. + * Sets the exception of extents of a local space bounding box within which particles are not + * spawned. It is aligned to the center of emitterExtents. This only applies to particle system + * with the shape `EMITTERSHAPE_BOX`. * * @type {import('../../../core/math/vec3.js').Vec3} */ @@ -484,13 +600,19 @@ class ParticleSystemComponent extends Component { this._setValue('emitterExtentsInner', arg); } + /** + * Gets the exception of extents of a local space bounding box within which particles are not + * spawned. + * + * @type {import('../../../core/math/vec3.js').Vec3} + */ get emitterExtentsInner() { return this.data.emitterExtentsInner; } /** - * (Only for EMITTERSHAPE_SPHERE) - * The radius within which particles are spawned at random positions. + * Sets the radius within which particles are spawned at random positions. This only applies to + * particle system with the shape `EMITTERSHAPE_SPHERE`. * * @type {number} */ @@ -498,13 +620,18 @@ class ParticleSystemComponent extends Component { this._setValue('emitterRadius', arg); } + /** + * Gets the radius within which particles are spawned at random positions. + * + * @type {number} + */ get emitterRadius() { return this.data.emitterRadius; } /** - * (Only for EMITTERSHAPE_SPHERE) - * The inner radius within which particles are not spawned. + * Sets the inner radius within which particles are not spawned. This only applies to particle + * system with the shape `EMITTERSHAPE_SPHERE`. * * @type {number} */ @@ -512,12 +639,17 @@ class ParticleSystemComponent extends Component { this._setValue('emitterRadiusInner', arg); } + /** + * Gets the inner radius within which particles are not spawned. + * + * @type {number} + */ get emitterRadiusInner() { return this.data.emitterRadiusInner; } /** - * Defines magnitude of the initial emitter velocity. Direction is given by emitter shape. + * Sets the magnitude of the initial emitter velocity. Direction is given by emitter shape. * * @type {number} */ @@ -525,12 +657,17 @@ class ParticleSystemComponent extends Component { this._setValue('initialVelocity', arg); } + /** + * Gets the magnitude of the initial emitter velocity. + * + * @type {number} + */ get initialVelocity() { return this.data.initialVelocity; } /** - * Enable particle wrapping. + * Sets whether particles wrap based on the set wrap bounds. * * @type {boolean} */ @@ -538,14 +675,19 @@ class ParticleSystemComponent extends Component { this._setValue('wrap', arg); } + /** + * Gets whether particles wrap based on the set wrap bounds. + * + * @type {boolean} + */ get wrap() { return this.data.wrap; } /** - * The half extents of a world space box volume centered on the owner entity's position. - * If a particle crosses the boundary of one side of the volume, it teleports to the - * opposite side. + * Sets the wrap bounds of the particle system. This is half extents of a world space box + * volume centered on the owner entity's position. If a particle crosses the boundary of one + * side of the volume, it teleports to the opposite side. * * @type {import('../../../core/math/vec3.js').Vec3} */ @@ -553,12 +695,17 @@ class ParticleSystemComponent extends Component { this._setValue('wrapBounds', arg); } + /** + * Gets the wrap bounds of the particle system. + * + * @type {import('../../../core/math/vec3.js').Vec3} + */ get wrapBounds() { return this.data.wrapBounds; } /** - * Binds particles to emitter transformation rather then world space. + * Sets whether particles move with respect to the emitter's transform rather then world space. * * @type {boolean} */ @@ -566,16 +713,21 @@ class ParticleSystemComponent extends Component { this._setValue('localSpace', arg); } + /** + * Gets whether particles move with respect to the emitter's transform rather then world space. + * + * @type {boolean} + */ get localSpace() { return this.data.localSpace; } /** - * Renders particles in 2D screen space. This needs to be set when particle system is part of - * hierarchy with {@link ScreenComponent} as its ancestor, and allows particle system to - * integrate with the rendering of {@link ElementComponent}s. Note that an entity with - * ParticleSystem component cannot be parented directly to {@link ScreenComponent}, but has to - * be a child of a {@link ElementComponent}, for example {@link LayoutGroupComponent}. + * Sets whether particles are rendered in 2D screen space. This needs to be set when particle + * system is part of hierarchy with {@link ScreenComponent} as its ancestor, and allows + * particle system to integrate with the rendering of {@link ElementComponent}s. Note that an + * entity with ParticleSystem component cannot be parented directly to {@link ScreenComponent}, + * but has to be a child of a {@link ElementComponent}, for example {@link LayoutGroupComponent}. * * @type {boolean} */ @@ -583,12 +735,17 @@ class ParticleSystemComponent extends Component { this._setValue('screenSpace', arg); } + /** + * Gets whether particles are rendered in 2D screen space. + * + * @type {boolean} + */ get screenSpace() { return this.data.screenSpace; } /** - * The {@link Asset} used to set the colorMap. + * Sets the {@link Asset} used to set the colorMap. * * @type {Asset} */ @@ -596,12 +753,17 @@ class ParticleSystemComponent extends Component { this._setValue('colorMapAsset', arg); } + /** + * Gets the {@link Asset} used to set the colorMap. + * + * @type {Asset} + */ get colorMapAsset() { return this.data.colorMapAsset; } /** - * The {@link Asset} used to set the normalMap. + * Sets the {@link Asset} used to set the normalMap. * * @type {Asset} */ @@ -609,13 +771,18 @@ class ParticleSystemComponent extends Component { this._setValue('normalMapAsset', arg); } + /** + * Gets the {@link Asset} used to set the normalMap. + * + * @type {Asset} + */ get normalMapAsset() { return this.data.normalMapAsset; } /** - * Triangular mesh to be used as a particle. Only first vertex/index buffer is used. Vertex buffer - * must contain local position at first 3 floats of each vertex. + * Sets the polygonal mesh to be used as a particle. Only first vertex/index buffer is used. + * Vertex buffer must contain local position at first 3 floats of each vertex. * * @type {Mesh} */ @@ -623,12 +790,17 @@ class ParticleSystemComponent extends Component { this._setValue('mesh', arg); } + /** + * Gets the polygonal mesh to be used as a particle. + * + * @type {Mesh} + */ get mesh() { return this.data.mesh; } /** - * The {@link Asset} used to set the mesh. + * Sets the {@link Asset} used to set the mesh. * * @type {Asset} */ @@ -636,12 +808,17 @@ class ParticleSystemComponent extends Component { this._setValue('meshAsset', arg); } + /** + * Gets the {@link Asset} used to set the mesh. + * + * @type {Asset} + */ get meshAsset() { return this.data.meshAsset; } /** - * The Render {@link Asset} used to set the mesh. + * Sets the Render {@link Asset} used to set the mesh. * * @type {Asset} */ @@ -649,15 +826,20 @@ class ParticleSystemComponent extends Component { this._setValue('renderAsset', arg); } + /** + * Gets the Render {@link Asset} used to set the mesh. + * + * @type {Asset} + */ get renderAsset() { return this.data.renderAsset; } /** - * Sorting mode. Forces CPU simulation, so be careful. + * Sets the particle orientation mode. Can be: * * - {@link PARTICLEORIENTATION_SCREEN}: Particles are facing camera. - * - {@link PARTICLEORIENTATION_WORLD}: User defines world space normal (particleNormal) to set + * - {@link PARTICLEORIENTATION_WORLD}: User defined world space normal (particleNormal) to set * planes orientation. * - {@link PARTICLEORIENTATION_EMITTER}: Similar to previous, but the normal is affected by * emitter (entity) transformation. @@ -668,14 +850,18 @@ class ParticleSystemComponent extends Component { this._setValue('orientation', arg); } + /** + * Gets the particle orientation mode. + * + * @type {number} + */ get orientation() { return this.data.orientation; } /** - * (Only for PARTICLEORIENTATION_WORLD and PARTICLEORIENTATION_EMITTER) - * The exception of extents of a local space bounding box within which particles are not spawned. - * Aligned to the center of EmitterExtents. + * Sets the particle normal. This only applies to particle system with the orientation modes + * `PARTICLEORIENTATION_WORLD` and `PARTICLEORIENTATION_EMITTER`. * * @type {import('../../../core/math/vec3.js').Vec3} */ @@ -683,12 +869,17 @@ class ParticleSystemComponent extends Component { this._setValue('particleNormal', arg); } + /** + * Gets the particle normal. + * + * @type {import('../../../core/math/vec3.js').Vec3} + */ get particleNormal() { return this.data.particleNormal; } /** - * Velocity relative to emitter over lifetime. + * Sets the local space velocity graph. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -696,12 +887,18 @@ class ParticleSystemComponent extends Component { this._setValue('localVelocityGraph', arg); } + /** + * Gets the local space velocity graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get localVelocityGraph() { return this.data.localVelocityGraph; } /** - * If not null, particles pick random values between localVelocityGraph and localVelocityGraph2. + * Sets the second velocity graph. If not null, particles pick random values between + * localVelocityGraph and localVelocityGraph2. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -709,12 +906,17 @@ class ParticleSystemComponent extends Component { this._setValue('localVelocityGraph2', arg); } + /** + * Gets the second velocity graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get localVelocityGraph2() { return this.data.localVelocityGraph2; } /** - * World-space velocity over lifetime. + * Sets the world space velocity graph. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -722,12 +924,18 @@ class ParticleSystemComponent extends Component { this._setValue('velocityGraph', arg); } + /** + * Gets the world space velocity graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get velocityGraph() { return this.data.velocityGraph; } /** - * If not null, particles pick random values between velocityGraph and velocityGraph2. + * Sets the second world space velocity graph. If not null, particles pick random values + * between velocityGraph and velocityGraph2. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -735,12 +943,17 @@ class ParticleSystemComponent extends Component { this._setValue('velocityGraph2', arg); } + /** + * Gets the second world space velocity graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get velocityGraph2() { return this.data.velocityGraph2; } /** - * Rotation speed over lifetime. + * Sets the rotation speed graph. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -748,12 +961,18 @@ class ParticleSystemComponent extends Component { this._setValue('rotationSpeedGraph', arg); } + /** + * Gets the rotation speed graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get rotationSpeedGraph() { return this.data.rotationSpeedGraph; } /** - * If not null, particles pick random values between rotationSpeedGraph and rotationSpeedGraph2. + * Sets the second rotation speed graph. If not null, particles pick random values between + * rotationSpeedGraph and rotationSpeedGraph2. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -761,12 +980,17 @@ class ParticleSystemComponent extends Component { this._setValue('rotationSpeedGraph2', arg); } + /** + * Gets the second rotation speed graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get rotationSpeedGraph2() { return this.data.rotationSpeedGraph2; } /** - * Radial speed over lifetime, velocity vector points from emitter origin to particle pos. + * Sets the radial speed graph. Velocity vector points from emitter origin to particle position. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -774,12 +998,19 @@ class ParticleSystemComponent extends Component { this._setValue('radialSpeedGraph', arg); } + /** + * Gets the radial speed graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get radialSpeedGraph() { return this.data.radialSpeedGraph; } /** - * If not null, particles pick random values between radialSpeedGraph and radialSpeedGraph2. + * Sets the second radial speed graph. If not null, particles pick random values between + * radialSpeedGraph and radialSpeedGraph2. Velocity vector points from emitter origin to + * particle position. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -787,12 +1018,17 @@ class ParticleSystemComponent extends Component { this._setValue('radialSpeedGraph2', arg); } + /** + * Gets the second radial speed graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get radialSpeedGraph2() { return this.data.radialSpeedGraph2; } /** - * Scale over lifetime. + * Sets the scale graph. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -800,12 +1036,18 @@ class ParticleSystemComponent extends Component { this._setValue('scaleGraph', arg); } + /** + * Gets the scale graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get scaleGraph() { return this.data.scaleGraph; } /** - * If not null, particles pick random values between scaleGraph and scaleGraph2. + * Sets the second scale graph. If not null, particles pick random values between `scaleGraph` + * and `scaleGraph2`. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -813,12 +1055,17 @@ class ParticleSystemComponent extends Component { this._setValue('scaleGraph2', arg); } + /** + * Gets the second scale graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get scaleGraph2() { return this.data.scaleGraph2; } /** - * Color over lifetime. + * Sets the color graph. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -826,12 +1073,18 @@ class ParticleSystemComponent extends Component { this._setValue('colorGraph', arg); } + /** + * Gets the color graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get colorGraph() { return this.data.colorGraph; } /** - * If not null, particles pick random values between colorGraph and colorGraph2. + * Sets the second color graph. If not null, particles pick random values between `colorGraph` + * and `colorGraph2`. * * @type {import('../../../core/math/curve-set.js').CurveSet} */ @@ -839,12 +1092,17 @@ class ParticleSystemComponent extends Component { this._setValue('colorGraph2', arg); } + /** + * Gets the second color graph. + * + * @type {import('../../../core/math/curve-set.js').CurveSet} + */ get colorGraph2() { return this.data.colorGraph2; } /** - * Alpha over lifetime. + * Sets the alpha graph. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -852,12 +1110,18 @@ class ParticleSystemComponent extends Component { this._setValue('alphaGraph', arg); } + /** + * Gets the alpha graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get alphaGraph() { return this.data.alphaGraph; } /** - * If not null, particles pick random values between alphaGraph and alphaGraph2. + * Sets the second alpha graph. If not null, particles pick random values between `alphaGraph` + * and `alphaGraph2`. * * @type {import('../../../core/math/curve.js').Curve} */ @@ -865,13 +1129,18 @@ class ParticleSystemComponent extends Component { this._setValue('alphaGraph2', arg); } + /** + * Gets the second alpha graph. + * + * @type {import('../../../core/math/curve.js').Curve} + */ get alphaGraph2() { return this.data.alphaGraph2; } /** - * The color map texture to apply to all particles in the system. If no texture is assigned, a - * default spot texture is used. + * Sets the color map texture to apply to all particles in the system. If no texture is + * assigned, a default spot texture is used. * * @type {import('../../../platform/graphics/texture.js').Texture} */ @@ -879,13 +1148,18 @@ class ParticleSystemComponent extends Component { this._setValue('colorMap', arg); } + /** + * Gets the color map texture to apply to all particles in the system. + * + * @type {import('../../../platform/graphics/texture.js').Texture} + */ get colorMap() { return this.data.colorMap; } /** - * The normal map texture to apply to all particles in the system. If no texture is assigned, - * an approximate spherical normal is calculated for each vertex. + * Sets the normal map texture to apply to all particles in the system. If no texture is + * assigned, an approximate spherical normal is calculated for each vertex. * * @type {import('../../../platform/graphics/texture.js').Texture} */ @@ -893,12 +1167,17 @@ class ParticleSystemComponent extends Component { this._setValue('normalMap', arg); } + /** + * Gets the normal map texture to apply to all particles in the system. + * + * @type {import('../../../platform/graphics/texture.js').Texture} + */ get normalMap() { return this.data.normalMap; } /** - * Number of horizontal tiles in the sprite sheet. + * Sets the number of horizontal tiles in the sprite sheet. * * @type {number} */ @@ -906,12 +1185,17 @@ class ParticleSystemComponent extends Component { this._setValue('animTilesX', arg); } + /** + * Gets the number of horizontal tiles in the sprite sheet. + * + * @type {number} + */ get animTilesX() { return this.data.animTilesX; } /** - * Number of vertical tiles in the sprite sheet. + * Sets the number of vertical tiles in the sprite sheet. * * @type {number} */ @@ -919,13 +1203,18 @@ class ParticleSystemComponent extends Component { this._setValue('animTilesY', arg); } + /** + * Gets the number of vertical tiles in the sprite sheet. + * + * @type {number} + */ get animTilesY() { return this.data.animTilesY; } /** - * The sprite sheet frame that the animation should begin playing from. Indexed from the start - * of the current animation. + * Sets the sprite sheet frame that the animation should begin playing from. Indexed from the + * start of the current animation. * * @type {number} */ @@ -933,13 +1222,19 @@ class ParticleSystemComponent extends Component { this._setValue('animStartFrame', arg); } + /** + * Gets the sprite sheet frame that the animation should begin playing from. + * + * @type {number} + */ get animStartFrame() { return this.data.animStartFrame; } /** - * Number of sprite sheet frames in the current sprite sheet animation. The number of animations - * multiplied by number of frames should be a value less than animTilesX multiplied by animTilesY. + * Sets the number of sprite sheet frames in the current sprite sheet animation. The number of + * animations multiplied by number of frames should be a value less than `animTilesX` + * multiplied by `animTilesY`. * * @type {number} */ @@ -947,14 +1242,19 @@ class ParticleSystemComponent extends Component { this._setValue('animNumFrames', arg); } + /** + * Gets the number of sprite sheet frames in the current sprite sheet animation. + * + * @type {number} + */ get animNumFrames() { return this.data.animNumFrames; } /** - * Number of sprite sheet animations contained within the current sprite sheet. The number of - * animations multiplied by number of frames should be a value less than animTilesX multiplied - * by animTilesY. + * Sets the number of sprite sheet animations contained within the current sprite sheet. The + * number of animations multiplied by number of frames should be a value less than `animTilesX` + * multiplied by `animTilesY`. * * @type {number} */ @@ -962,13 +1262,18 @@ class ParticleSystemComponent extends Component { this._setValue('animNumAnimations', arg); } + /** + * Gets the number of sprite sheet animations contained within the current sprite sheet. + * + * @type {number} + */ get animNumAnimations() { return this.data.animNumAnimations; } /** - * When animNumAnimations is greater than 1, the sprite sheet animation index determines which - * animation the particle system should play. + * Sets the index of the animation to play. When `animNumAnimations` is greater than 1, the + * sprite sheet animation index determines which animation the particle system should play. * * @type {number} */ @@ -976,26 +1281,38 @@ class ParticleSystemComponent extends Component { this._setValue('animIndex', arg); } + /** + * Gets the index of the animation to play. + * + * @type {number} + */ get animIndex() { return this.data.animIndex; } /** - * Each particle emitted by the system will play a random animation from the sprite sheet, up to - * animNumAnimations. + * Sets whether each particle emitted by the system will play a random animation from the + * sprite sheet, up to `animNumAnimations`. * - * @type {number} + * @type {boolean} */ set randomizeAnimIndex(arg) { this._setValue('randomizeAnimIndex', arg); } + /** + * Gets whether each particle emitted by the system will play a random animation from the + * sprite sheet, up to `animNumAnimations`. + * + * @type {boolean} + */ get randomizeAnimIndex() { return this.data.randomizeAnimIndex; } /** - * Sprite sheet animation speed. 1 = particle lifetime, 2 = twice during lifetime etc. + * Sets the sprite sheet animation speed. 1 = particle lifetime, 2 = double the particle + * lifetime, etc. * * @type {number} */ @@ -1003,12 +1320,17 @@ class ParticleSystemComponent extends Component { this._setValue('animSpeed', arg); } + /** + * Gets the sprite sheet animation speed. + * + * @type {number} + */ get animSpeed() { return this.data.animSpeed; } /** - * Controls whether the sprite sheet animation plays once or loops continuously. + * Sets whether the sprite sheet animation plays once or loops continuously. * * @type {boolean} */ @@ -1016,13 +1338,18 @@ class ParticleSystemComponent extends Component { this._setValue('animLoop', arg); } + /** + * Gets whether the sprite sheet animation plays once or loops continuously. + * + * @type {boolean} + */ get animLoop() { return this.data.animLoop; } /** - * An array of layer IDs ({@link Layer#id}) to which this particle system should belong. Don't - * push/pop/splice or modify this array, if you want to change it - set a new one instead. + * Sets the array of layer IDs ({@link Layer#id}) to which this particle system should belong. + * Don't push/pop/splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -1030,11 +1357,20 @@ class ParticleSystemComponent extends Component { this._setValue('layers', arg); } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this particle system belongs. + * + * @type {number[]} + */ get layers() { return this.data.layers; } /** + * Sets the draw order of the component. A higher value means that the component will be + * rendered on top of other components in the same layer. This is not used unless the layer's + * sort order is set to {@link SORTMODE_MANUAL}. + * * @type {number} */ set drawOrder(drawOrder) { @@ -1044,6 +1380,11 @@ class ParticleSystemComponent extends Component { } } + /** + * Gets the draw order of the component. + * + * @type {number} + */ get drawOrder() { return this._drawOrder; } diff --git a/src/framework/components/render/component.js b/src/framework/components/render/component.js index e648728c576..e9885b66168 100644 --- a/src/framework/components/render/component.js +++ b/src/framework/components/render/component.js @@ -144,7 +144,7 @@ class RenderComponent extends Component { } /** - * Set rendering of all {@link MeshInstance}s to the specified render style. Can be: + * Sets the render style of this component's {@link MeshInstance}s. Can be: * * - {@link RENDERSTYLE_SOLID} * - {@link RENDERSTYLE_WIREFRAME} @@ -161,17 +161,22 @@ class RenderComponent extends Component { } } + /** + * Gets the render style of this component's {@link MeshInstance}s. + * + * @type {number} + */ get renderStyle() { return this._renderStyle; } /** - * If set, the object space bounding box is used as a bounding box for visibility culling of - * attached mesh instances. This is an optimization, allowing oversized bounding box to be - * specified for skinned characters in order to avoid per frame bounding box computations based - * on bone positions. + * Sets the custom object space bounding box that is used for visibility culling of attached + * mesh instances. This is an optimization, allowing an oversized bounding box to be specified + * for skinned characters in order to avoid per frame bounding box computations based on bone + * positions. * - * @type {import('../../../core/shape/bounding-box.js').BoundingBox} + * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} */ set customAabb(value) { this._customAabb = value; @@ -185,12 +190,18 @@ class RenderComponent extends Component { } } + /** + * Gets the custom object space bounding box that is used for visibility culling of attached + * mesh instances. + * + * @type {import('../../../core/shape/bounding-box.js').BoundingBox|null} + */ get customAabb() { return this._customAabb; } /** - * The type of the render. Can be one of the following: + * Sets the type of the component. Can be one of the following: * * - "asset": The component will render a render asset * - "box": The component will render a box (1 unit in each dimension) @@ -226,13 +237,17 @@ class RenderComponent extends Component { } } + /** + * Gets the type of the component. + * + * @type {string} + */ get type() { return this._type; } /** - * An array of meshInstances contained in the component. If meshes are not set or loaded for - * component it will return null. + * Sets the array of meshInstances contained in the component. * * @type {MeshInstance[]} */ @@ -266,12 +281,18 @@ class RenderComponent extends Component { } } + /** + * Gets the array of meshInstances contained in the component. + * + * @type {MeshInstance[]} + */ get meshInstances() { return this._meshInstances; } /** - * If true, the meshes will be lightmapped after using lightmapper.bake(). + * Sets whether the component is affected by the runtime lightmapper. If true, the meshes will + * be lightmapped after using lightmapper.bake(). * * @type {boolean} */ @@ -288,12 +309,17 @@ class RenderComponent extends Component { } } + /** + * Gets whether the component is affected by the runtime lightmapper. + * + * @type {boolean} + */ get lightmapped() { return this._lightmapped; } /** - * If true, attached meshes will cast shadows for lights that have shadow casting enabled. + * Sets whether attached meshes will cast shadows for lights that have shadow casting enabled. * * @type {boolean} */ @@ -332,12 +358,17 @@ class RenderComponent extends Component { } } + /** + * Gets whether attached meshes will cast shadows for lights that have shadow casting enabled. + * + * @type {boolean} + */ get castShadows() { return this._castShadows; } /** - * If true, shadows will be cast on attached meshes. + * Sets whether shadows will be cast on attached meshes. * * @type {boolean} */ @@ -355,12 +386,17 @@ class RenderComponent extends Component { } } + /** + * Gets whether shadows will be cast on attached meshes. + * + * @type {boolean} + */ get receiveShadows() { return this._receiveShadows; } /** - * If true, the meshes will cast shadows when rendering lightmaps. + * Sets whether meshes instances will cast shadows when rendering lightmaps. * * @type {boolean} */ @@ -368,12 +404,17 @@ class RenderComponent extends Component { this._castShadowsLightmap = value; } + /** + * Gets whether meshes instances will cast shadows when rendering lightmaps. + * + * @type {boolean} + */ get castShadowsLightmap() { return this._castShadowsLightmap; } /** - * Lightmap resolution multiplier. + * Sets the lightmap resolution multiplier. * * @type {number} */ @@ -381,13 +422,18 @@ class RenderComponent extends Component { this._lightmapSizeMultiplier = value; } + /** + * Gets the lightmap resolution multiplier. + * + * @type {number} + */ get lightmapSizeMultiplier() { return this._lightmapSizeMultiplier; } /** - * An array of layer IDs ({@link Layer#id}) to which the meshes should belong. Don't push, pop, - * splice or modify this array, if you want to change it - set a new one instead. + * Sets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong. Don't + * push, pop, splice or modify this array. If you want to change it, set a new one instead. * * @type {number[]} */ @@ -423,12 +469,18 @@ class RenderComponent extends Component { } } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong. + * + * @type {number[]} + */ get layers() { return this._layers; } /** - * Assign meshes to a specific batch group (see {@link BatchGroup}). Default is -1 (no group). + * Sets the batch group for the mesh instances in this component (see {@link BatchGroup}). + * Default is -1 (no group). * * @type {number} */ @@ -451,13 +503,18 @@ class RenderComponent extends Component { } } + /** + * Gets the batch group for the mesh instances in this component (see {@link BatchGroup}). + * + * @type {number} + */ get batchGroupId() { return this._batchGroupId; } /** - * The material {@link Material} that will be used to render the meshes (not used on renders of - * type 'asset'). + * Sets the material {@link Material} that will be used to render the component. The material + * is ignored for renders of type 'asset'. * * @type {import('../../../scene/materials/material.js').Material} */ @@ -473,13 +530,18 @@ class RenderComponent extends Component { } } + /** + * Gets the material {@link Material} that will be used to render the component. + * + * @type {import('../../../scene/materials/material.js').Material} + */ get material() { return this._material; } /** - * The material assets that will be used to render the meshes. Each material corresponds to the - * respective mesh instance. + * Sets the material assets that will be used to render the component. Each material + * corresponds to the respective mesh instance. * * @type {Asset[]|number[]} */ @@ -527,6 +589,11 @@ class RenderComponent extends Component { } } + /** + * Gets the material assets that will be used to render the component. + * + * @type {Asset[]|number[]} + */ get materialAssets() { return this._materialReferences.map(function (ref) { return ref.id; @@ -534,8 +601,8 @@ class RenderComponent extends Component { } /** - * The render asset for the render component (only applies to type 'asset') - can also be an - * asset id. + * Sets the render asset (or asset id) for the render component. This only applies to render components with + * type 'asset'. * * @type {Asset|number} */ @@ -554,6 +621,11 @@ class RenderComponent extends Component { } } + /** + * Gets the render asset id for the render component. + * + * @type {number} + */ get asset() { return this._assetReference.id; } diff --git a/src/framework/components/rigid-body/component.js b/src/framework/components/rigid-body/component.js index 2a35c63129e..226cc5a5ab0 100644 --- a/src/framework/components/rigid-body/component.js +++ b/src/framework/components/rigid-body/component.js @@ -182,7 +182,7 @@ class RigidBodyComponent extends Component { } /** - * Controls the rate at which a body loses angular velocity over time. + * Sets the rate at which a body loses angular velocity over time. * * @type {number} */ @@ -196,13 +196,18 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the rate at which a body loses angular velocity over time. + * + * @type {number} + */ get angularDamping() { return this._angularDamping; } /** - * Scaling factor for angular movement of the body in each axis. Only valid for rigid bodies of - * type {@link BODYTYPE_DYNAMIC}. Defaults to 1 in all axes (body can freely rotate). + * Sets the scaling factor for angular movement of the body in each axis. Only valid for rigid + * bodies of type {@link BODYTYPE_DYNAMIC}. Defaults to 1 in all axes (body can freely rotate). * * @type {Vec3} */ @@ -217,12 +222,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the scaling factor for angular movement of the body in each axis. + * + * @type {Vec3} + */ get angularFactor() { return this._angularFactor; } /** - * Defines the rotational speed of the body around each world axis. + * Sets the rotational speed of the body around each world axis. * * @type {Vec3} */ @@ -237,6 +247,11 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the rotational speed of the body around each world axis. + * + * @type {Vec3} + */ get angularVelocity() { if (this._body && this._type === BODYTYPE_DYNAMIC) { const velocity = this._body.getAngularVelocity(); @@ -260,7 +275,7 @@ class RigidBodyComponent extends Component { } /** - * The friction value used when contacts occur between two bodies. A higher value indicates + * Sets the friction value used when contacts occur between two bodies. A higher value indicates * more friction. Should be set in the range 0 to 1. Defaults to 0.5. * * @type {number} @@ -275,12 +290,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the friction value used when contacts occur between two bodies. + * + * @type {number} + */ get friction() { return this._friction; } /** - * The collision group this body belongs to. Combine the group and the mask to prevent bodies + * Sets the collision group this body belongs to. Combine the group and the mask to prevent bodies * colliding with each other. Defaults to 1. * * @type {number} @@ -297,12 +317,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the collision group this body belongs to. + * + * @type {number} + */ get group() { return this._group; } /** - * Controls the rate at which a body loses linear velocity over time. Defaults to 0. + * Sets the rate at which a body loses linear velocity over time. Defaults to 0. * * @type {number} */ @@ -316,13 +341,18 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the rate at which a body loses linear velocity over time. + * + * @type {number} + */ get linearDamping() { return this._linearDamping; } /** - * Scaling factor for linear movement of the body in each axis. Only valid for rigid bodies of - * type {@link BODYTYPE_DYNAMIC}. Defaults to 1 in all axes (body can freely move). + * Sets the scaling factor for linear movement of the body in each axis. Only valid for rigid + * bodies of type {@link BODYTYPE_DYNAMIC}. Defaults to 1 in all axes (body can freely move). * * @type {Vec3} */ @@ -337,12 +367,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the scaling factor for linear movement of the body in each axis. + * + * @type {Vec3} + */ get linearFactor() { return this._linearFactor; } /** - * Defines the speed of the body in a given direction. + * Sets the speed of the body in a given direction. * * @type {Vec3} */ @@ -357,6 +392,11 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the speed of the body in a given direction. + * + * @type {Vec3} + */ get linearVelocity() { if (this._body && this._type === BODYTYPE_DYNAMIC) { const velocity = this._body.getLinearVelocity(); @@ -366,8 +406,8 @@ class RigidBodyComponent extends Component { } /** - * The collision mask sets which groups this body collides with. It is a bitfield of 16 bits, - * the first 8 bits are reserved for engine use. Defaults to 65535. + * Sets the collision mask sets which groups this body collides with. It is a bit field of 16 + * bits, the first 8 bits are reserved for engine use. Defaults to 65535. * * @type {number} */ @@ -383,13 +423,18 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the collision mask sets which groups this body collides with. + * + * @type {number} + */ get mask() { return this._mask; } /** - * The mass of the body. This is only relevant for {@link BODYTYPE_DYNAMIC} bodies, other types - * have infinite mass. Defaults to 1. + * Sets the mass of the body. This is only relevant for {@link BODYTYPE_DYNAMIC} bodies, other + * types have infinite mass. Defaults to 1. * * @type {number} */ @@ -416,15 +461,20 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the mass of the body. + * + * @type {number} + */ get mass() { return this._mass; } /** - * Influences the amount of energy lost when two rigid bodies collide. The calculation - * multiplies the restitution values for both colliding bodies. A multiplied value of 0 means - * that all energy is lost in the collision while a value of 1 means that no energy is lost. - * Should be set in the range 0 to 1. Defaults to 0. + * Sets the value that controls the amount of energy lost when two rigid bodies collide. The + * calculation multiplies the restitution values for both colliding bodies. A multiplied value + * of 0 means that all energy is lost in the collision while a value of 1 means that no energy + * is lost. Should be set in the range 0 to 1. Defaults to 0. * * @type {number} */ @@ -438,12 +488,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the value that controls the amount of energy lost when two rigid bodies collide. + * + * @type {number} + */ get restitution() { return this._restitution; } /** - * Sets a torsional friction orthogonal to the contact point. Defaults to 0. + * Sets the torsional friction orthogonal to the contact point. Defaults to 0. * * @type {number} */ @@ -457,12 +512,17 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the torsional friction orthogonal to the contact point. + * + * @type {number} + */ get rollingFriction() { return this._rollingFriction; } /** - * The rigid body type determines how the body is simulated. Can be: + * Sets the rigid body type determines how the body is simulated. Can be: * * - {@link BODYTYPE_STATIC}: infinite mass and cannot move. * - {@link BODYTYPE_DYNAMIC}: simulated according to applied forces. @@ -501,6 +561,11 @@ class RigidBodyComponent extends Component { } } + /** + * Gets the rigid body type determines how the body is simulated. + * + * @type {string} + */ get type() { return this._type; } @@ -668,16 +733,16 @@ class RigidBodyComponent extends Component { * signatures. You can either specify the force (and optional relative point) via 3D-vector or * numbers. * - * @param {Vec3|number} x - A 3-dimensional vector representing the force in world-space or - * the x-component of the force in world-space. + * @param {Vec3|number} x - A 3-dimensional vector representing the force in world space or + * the x-component of the force in world space. * @param {Vec3|number} [y] - An optional 3-dimensional vector representing the relative point - * at which to apply the impulse in world-space or the y-component of the force in world-space. - * @param {number} [z] - The z-component of the force in world-space. - * @param {number} [px] - The x-component of a world-space offset from the body's position + * at which to apply the impulse in world space or the y-component of the force in world space. + * @param {number} [z] - The z-component of the force in world space. + * @param {number} [px] - The x-component of a world space offset from the body's position * where the force is applied. - * @param {number} [py] - The y-component of a world-space offset from the body's position + * @param {number} [py] - The y-component of a world space offset from the body's position * where the force is applied. - * @param {number} [pz] - The z-component of a world-space offset from the body's position + * @param {number} [pz] - The z-component of a world space offset from the body's position * where the force is applied. * @example * // Apply an approximation of gravity at the body's center @@ -732,10 +797,10 @@ class RigidBodyComponent extends Component { * Apply torque (rotational force) to the body. This function has two valid signatures. You can * either specify the torque force with a 3D-vector or with 3 numbers. * - * @param {Vec3|number} x - A 3-dimensional vector representing the torque force in world-space - * or the x-component of the torque force in world-space. - * @param {number} [y] - The y-component of the torque force in world-space. - * @param {number} [z] - The z-component of the torque force in world-space. + * @param {Vec3|number} x - A 3-dimensional vector representing the torque force in world space + * or the x-component of the torque force in world space. + * @param {number} [y] - The y-component of the torque force in world space. + * @param {number} [z] - The z-component of the torque force in world space. * @example * // Apply via vector * const torque = new pc.Vec3(0, 10, 0); @@ -763,34 +828,34 @@ class RigidBodyComponent extends Component { * has two valid signatures. You can either specify the impulse (and optional relative point) * via 3D-vector or numbers. * - * @param {Vec3|number} x - A 3-dimensional vector representing the impulse in world-space or - * the x-component of the impulse in world-space. + * @param {Vec3|number} x - A 3-dimensional vector representing the impulse in world space or + * the x-component of the impulse in world space. * @param {Vec3|number} [y] - An optional 3-dimensional vector representing the relative point - * at which to apply the impulse in the local-space of the entity or the y-component of the - * impulse to apply in world-space. - * @param {number} [z] - The z-component of the impulse to apply in world-space. + * at which to apply the impulse in the local space of the entity or the y-component of the + * impulse to apply in world space. + * @param {number} [z] - The z-component of the impulse to apply in world space. * @param {number} [px] - The x-component of the point at which to apply the impulse in the - * local-space of the entity. + * local space of the entity. * @param {number} [py] - The y-component of the point at which to apply the impulse in the - * local-space of the entity. + * local space of the entity. * @param {number} [pz] - The z-component of the point at which to apply the impulse in the - * local-space of the entity. + * local space of the entity. * @example - * // Apply an impulse along the world-space positive y-axis at the entity's position. + * // Apply an impulse along the world space positive y-axis at the entity's position. * const impulse = new pc.Vec3(0, 10, 0); * entity.rigidbody.applyImpulse(impulse); * @example - * // Apply an impulse along the world-space positive y-axis at 1 unit down the positive - * // z-axis of the entity's local-space. + * // Apply an impulse along the world space positive y-axis at 1 unit down the positive + * // z-axis of the entity's local space. * const impulse = new pc.Vec3(0, 10, 0); * const relativePoint = new pc.Vec3(0, 0, 1); * entity.rigidbody.applyImpulse(impulse, relativePoint); * @example - * // Apply an impulse along the world-space positive y-axis at the entity's position. + * // Apply an impulse along the world space positive y-axis at the entity's position. * entity.rigidbody.applyImpulse(0, 10, 0); * @example - * // Apply an impulse along the world-space positive y-axis at 1 unit down the positive - * // z-axis of the entity's local-space. + * // Apply an impulse along the world space positive y-axis at 1 unit down the positive + * // z-axis of the entity's local space. * entity.rigidbody.applyImpulse(0, 10, 0, 0, 0, 1); */ applyImpulse(x, y, z, px, py, pz) { @@ -822,9 +887,9 @@ class RigidBodyComponent extends Component { * numbers. * * @param {Vec3|number} x - A 3-dimensional vector representing the torque impulse in - * world-space or the x-component of the torque impulse in world-space. - * @param {number} [y] - The y-component of the torque impulse in world-space. - * @param {number} [z] - The z-component of the torque impulse in world-space. + * world space or the x-component of the torque impulse in world space. + * @param {number} [y] - The y-component of the torque impulse in world space. + * @param {number} [z] - The z-component of the torque impulse in world space. * @example * // Apply via vector * const torque = new pc.Vec3(0, 10, 0); @@ -985,7 +1050,7 @@ class RigidBodyComponent extends Component { } /** - * Teleport an entity to a new world-space position, optionally setting orientation. This + * Teleport an entity to a new world space position, optionally setting orientation. This * function should only be called for rigid bodies that are dynamic. This function has three * valid signatures. The first takes a 3-dimensional vector for the position and an optional * 3-dimensional vector for Euler rotation. The second takes a 3-dimensional vector for the @@ -1007,11 +1072,11 @@ class RigidBodyComponent extends Component { * // Teleport the entity to the origin * entity.rigidbody.teleport(0, 0, 0); * @example - * // Teleport the entity to world-space coordinate [1, 2, 3] and reset orientation + * // Teleport the entity to world space coordinate [1, 2, 3] and reset orientation * const position = new pc.Vec3(1, 2, 3); * entity.rigidbody.teleport(position, pc.Vec3.ZERO); * @example - * // Teleport the entity to world-space coordinate [1, 2, 3] and reset orientation + * // Teleport the entity to world space coordinate [1, 2, 3] and reset orientation * entity.rigidbody.teleport(1, 2, 3, 0, 0, 0); */ teleport(x, y, z, rx, ry, rz) { diff --git a/src/framework/components/screen/component.js b/src/framework/components/screen/component.js index 7582d00fddd..e04cab1a1db 100644 --- a/src/framework/components/screen/component.js +++ b/src/framework/components/screen/component.js @@ -38,7 +38,7 @@ class ScreenComponent extends Component { this._screenSpace = false; /** - * If true then elements inside this screen will be not be rendered when outside of the + * If true, then elements inside this screen will be not be rendered when outside of the * screen (only valid when screenSpace is true). * * @type {boolean} @@ -156,7 +156,7 @@ class ScreenComponent extends Component { } /** - * The width and height of the ScreenComponent. When screenSpace is true the resolution will + * Sets the width and height of the ScreenComponent. When screenSpace is true the resolution will * always be equal to {@link GraphicsDevice#width} x {@link GraphicsDevice#height}. * * @type {Vec2} @@ -180,14 +180,20 @@ class ScreenComponent extends Component { this._elements.forEach(element => element._onScreenResize(this._resolution)); } + /** + * Gets the width and height of the ScreenComponent. + * + * @type {Vec2} + */ get resolution() { return this._resolution; } /** - * The resolution that the ScreenComponent is designed for. This is only taken into account - * when screenSpace is true and scaleMode is {@link SCALEMODE_BLEND}. If the actual resolution - * is different then the ScreenComponent will be scaled according to the scaleBlend value. + * Sets the resolution that the ScreenComponent is designed for. This is only taken into + * account when screenSpace is true and scaleMode is {@link SCALEMODE_BLEND}. If the actual + * resolution is different then the ScreenComponent will be scaled according to the scaleBlend + * value. * * @type {Vec2} */ @@ -203,6 +209,11 @@ class ScreenComponent extends Component { this._elements.forEach(element => element._onScreenResize(this._resolution)); } + /** + * Gets the resolution that the ScreenComponent is designed for. + * + * @type {Vec2} + */ get referenceResolution() { if (this._scaleMode === SCALEMODE_NONE) { return this._resolution; @@ -211,7 +222,7 @@ class ScreenComponent extends Component { } /** - * If true then the ScreenComponent will render its child {@link ElementComponent}s in screen + * Sets whether the ScreenComponent will render its child {@link ElementComponent}s in screen * space instead of world space. Enable this to create 2D user interfaces. * * @type {boolean} @@ -231,13 +242,19 @@ class ScreenComponent extends Component { this._elements.forEach(element => element._onScreenSpaceChange()); } + /** + * Gets whether the ScreenComponent will render its child {@link ElementComponent}s in screen + * space instead of world space. + * + * @type {boolean} + */ get screenSpace() { return this._screenSpace; } /** - * Can either be {@link SCALEMODE_NONE} or {@link SCALEMODE_BLEND}. See the description of - * referenceResolution for more information. + * Sets the scale mode. Can either be {@link SCALEMODE_NONE} or {@link SCALEMODE_BLEND}. See + * the description of referenceResolution for more information. * * @type {string} */ @@ -256,14 +273,19 @@ class ScreenComponent extends Component { this.fire('set:scalemode', this._scaleMode); } + /** + * Gets the scale mode. + * + * @type {string} + */ get scaleMode() { return this._scaleMode; } /** - * A value between 0 and 1 that is used when scaleMode is equal to {@link SCALEMODE_BLEND}. - * Scales the ScreenComponent with width as a reference (when value is 0), the height as a - * reference (when value is 1) or anything in between. + * Sets the scale blend. This is a value between 0 and 1 that is used when scaleMode is equal + * to {@link SCALEMODE_BLEND}. Scales the ScreenComponent with width as a reference (when value + * is 0), the height as a reference (when value is 1) or anything in between. * * @type {number} */ @@ -280,14 +302,19 @@ class ScreenComponent extends Component { this._elements.forEach(element => element._onScreenResize(this._resolution)); } + /** + * Gets the scale blend. + * + * @type {number} + */ get scaleBlend() { return this._scaleBlend; } /** - * Priority determines the order in which Screen components in the same layer are rendered. - * Number must be an integer between 0 and 255. Priority is set into the top 8 bits of the - * drawOrder property in an element. + * Sets the priority. Priority determines the order in which Screen components in the same + * layer are rendered. Number must be an integer between 0 and 255. Priority is set into the + * top 8 bits of the drawOrder property in an element. * * @type {number} */ @@ -304,6 +331,11 @@ class ScreenComponent extends Component { this.syncDrawOrder(); } + /** + * Gets the priority. + * + * @type {number} + */ get priority() { return this._priority; } diff --git a/src/framework/components/script/component.js b/src/framework/components/script/component.js index c182759bf74..f36c02d3a1f 100644 --- a/src/framework/components/script/component.js +++ b/src/framework/components/script/component.js @@ -188,8 +188,8 @@ class ScriptComponent extends Component { } /** - * An array of all script instances attached to an entity. This array is read-only and should - * not be modified by developer. + * Sets the array of all script instances attached to an entity. This array is read-only and + * should not be modified by developer. * * @type {import('../../script/script-type.js').ScriptType[]} */ @@ -233,6 +233,11 @@ class ScriptComponent extends Component { } } + /** + * Gets the array of all script instances attached to an entity. + * + * @type {import('../../script/script-type.js').ScriptType[]} + */ get scripts() { return this._scripts; } diff --git a/src/framework/components/scroll-view/component.js b/src/framework/components/scroll-view/component.js index 97306bf5792..ad775e4053d 100644 --- a/src/framework/components/scroll-view/component.js +++ b/src/framework/components/scroll-view/component.js @@ -95,18 +95,25 @@ class ScrollViewComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { this._setValue('enabled', arg); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } /** - * Whether to enable horizontal scrolling. + * Sets whether horizontal scrolling is enabled. * * @type {boolean} */ @@ -114,12 +121,17 @@ class ScrollViewComponent extends Component { this._setValue('horizontal', arg); } + /** + * Gets whether horizontal scrolling is enabled. + * + * @type {boolean} + */ get horizontal() { return this.data.horizontal; } /** - * Whether to enable vertical scrolling. + * Sets whether vertical scrolling is enabled. * * @type {boolean} */ @@ -127,13 +139,18 @@ class ScrollViewComponent extends Component { this._setValue('vertical', arg); } + /** + * Gets whether vertical scrolling is enabled. + * + * @type {boolean} + */ get vertical() { return this.data.vertical; } /** - * Specifies how the scroll view should behave when the user scrolls past the end of the content. - * Modes are defined as follows: + * Sets the scroll mode of the scroll viewer. Specifies how the scroll view should behave when + * the user scrolls past the end of the content. Modes are defined as follows: * * - {@link SCROLL_MODE_CLAMP}: Content does not scroll any further than its bounds. * - {@link SCROLL_MODE_BOUNCE}: Content scrolls past its bounds and then gently bounces back. @@ -145,12 +162,17 @@ class ScrollViewComponent extends Component { this._setValue('scrollMode', arg); } + /** + * Gets the scroll mode of the scroll viewer. + * + * @type {number} + */ get scrollMode() { return this.data.scrollMode; } /** - * Controls how far the content should move before bouncing back. + * Sets how far the content should move before bouncing back. * * @type {number} */ @@ -158,12 +180,17 @@ class ScrollViewComponent extends Component { this._setValue('bounceAmount', arg); } + /** + * Gets how far the content should move before bouncing back. + * + * @type {number} + */ get bounceAmount() { return this.data.bounceAmount; } /** - * Controls how freely the content should move if thrown, i.e. By flicking on a phone or by + * Sets how freely the content should move if thrown, i.e. By flicking on a phone or by * flinging the scroll wheel on a mouse. A value of 1 means that content will stop immediately; * 0 means that content will continue moving forever (or until the bounds of the content are * reached, depending on the scrollMode). @@ -174,14 +201,15 @@ class ScrollViewComponent extends Component { this._setValue('friction', arg); } + /** + * Gets how freely the content should move if thrown. + * + * @type {number} + */ get friction() { return this.data.friction; } - /** - * @type {number} - * @ignore - */ set dragThreshold(arg) { this._setValue('dragThreshold', arg); } @@ -191,7 +219,7 @@ class ScrollViewComponent extends Component { } /** - * Whether to use mouse wheel for scrolling (horizontally and vertically). + * Sets whether to use mouse wheel for scrolling (horizontally and vertically). * * @type {boolean} */ @@ -199,15 +227,20 @@ class ScrollViewComponent extends Component { this._setValue('useMouseWheel', arg); } + /** + * Gets whether to use mouse wheel for scrolling (horizontally and vertically). + * + * @type {boolean} + */ get useMouseWheel() { return this.data.useMouseWheel; } /** - * Mouse wheel horizontal and vertical sensitivity. Only used if useMouseWheel is set. Setting a - * direction to 0 will disable mouse wheel scrolling in that direction. 1 is a default - * sensitivity that is considered to feel good. The values can be set higher or lower than 1 to - * tune the sensitivity. Defaults to [1, 1]. + * Sets the mouse wheel horizontal and vertical sensitivity. Only used if useMouseWheel is set. + * Setting a direction to 0 will disable mouse wheel scrolling in that direction. 1 is a + * default sensitivity that is considered to feel good. The values can be set higher or lower + * than 1 to tune the sensitivity. Defaults to [1, 1]. * * @type {Vec2} */ @@ -215,13 +248,18 @@ class ScrollViewComponent extends Component { this._setValue('mouseWheelSensitivity', arg); } + /** + * Gets the mouse wheel horizontal and vertical sensitivity. + * + * @type {Vec2} + */ get mouseWheelSensitivity() { return this.data.mouseWheelSensitivity; } /** - * Controls whether the horizontal scrollbar should be visible all the time, or only visible - * when the content exceeds the size of the viewport. + * Sets whether the horizontal scrollbar should be visible all the time, or only visible when + * the content exceeds the size of the viewport. * * @type {number} */ @@ -229,13 +267,19 @@ class ScrollViewComponent extends Component { this._setValue('horizontalScrollbarVisibility', arg); } + /** + * Gets whether the horizontal scrollbar should be visible all the time, or only visible when + * the content exceeds the size of the viewport. + * + * @type {number} + */ get horizontalScrollbarVisibility() { return this.data.horizontalScrollbarVisibility; } /** - * Controls whether the vertical scrollbar should be visible all the time, or only visible when - * the content exceeds the size of the viewport. + * Sets whether the vertical scrollbar should be visible all the time, or only visible when the + * content exceeds the size of the viewport. * * @type {number} */ @@ -243,12 +287,18 @@ class ScrollViewComponent extends Component { this._setValue('verticalScrollbarVisibility', arg); } + /** + * Gets whether the vertical scrollbar should be visible all the time, or only visible when the + * content exceeds the size of the viewport. + * + * @type {number} + */ get verticalScrollbarVisibility() { return this.data.verticalScrollbarVisibility; } /** - * The entity to be used as the masked viewport area, within which the content will scroll. + * Sets the entity to be used as the masked viewport area, within which the content will scroll. * This entity must have an ElementGroup component. * * @type {import('../../../framework/entity.js').Entity} @@ -257,13 +307,18 @@ class ScrollViewComponent extends Component { this._setValue('viewportEntity', arg); } + /** + * Gets the entity to be used as the masked viewport area, within which the content will scroll. + * + * @type {import('../../../framework/entity.js').Entity} + */ get viewportEntity() { return this.data.viewportEntity; } /** - * The entity which contains the scrolling content itself. This entity must have an Element - * component. + * Sets the entity which contains the scrolling content itself. This entity must have an + * {@link ElementComponent}. * * @type {import('../../../framework/entity.js').Entity} */ @@ -271,12 +326,18 @@ class ScrollViewComponent extends Component { this._setValue('contentEntity', arg); } + /** + * Gets the entity which contains the scrolling content itself. + * + * @type {import('../../../framework/entity.js').Entity} + */ get contentEntity() { return this.data.contentEntity; } /** - * The entity to be used as the vertical scrollbar. This entity must have a Scrollbar component. + * Sets the entity to be used as the horizontal scrollbar. This entity must have a + * {@link ScrollbarComponent}. * * @type {import('../../../framework/entity.js').Entity} */ @@ -284,12 +345,18 @@ class ScrollViewComponent extends Component { this._setValue('horizontalScrollbarEntity', arg); } + /** + * Gets the entity to be used as the horizontal scrollbar. + * + * @type {import('../../../framework/entity.js').Entity} + */ get horizontalScrollbarEntity() { return this.data.horizontalScrollbarEntity; } /** - * The entity to be used as the vertical scrollbar. This entity must have a Scrollbar component. + * Sets the entity to be used as the vertical scrollbar. This entity must have a + * {@link ScrollbarComponent}. * * @type {import('../../../framework/entity.js').Entity} */ @@ -297,12 +364,17 @@ class ScrollViewComponent extends Component { this._setValue('verticalScrollbarEntity', arg); } + /** + * Gets the entity to be used as the vertical scrollbar. + * + * @type {import('../../../framework/entity.js').Entity} + */ get verticalScrollbarEntity() { return this.data.verticalScrollbarEntity; } /** - * Set scroll value. + * Sets the scroll value. * * @type {Vec2} */ @@ -310,6 +382,11 @@ class ScrollViewComponent extends Component { this._onSetScroll(value.x, value.y); } + /** + * Gets the scroll value. + * + * @type {Vec2} + */ get scroll() { return this._scroll; } diff --git a/src/framework/components/scrollbar/component.js b/src/framework/components/scrollbar/component.js index cfad81ae012..f2869185de8 100644 --- a/src/framework/components/scrollbar/component.js +++ b/src/framework/components/scrollbar/component.js @@ -59,18 +59,25 @@ class ScrollbarComponent extends Component { } /** + * Sets the enabled state of the component. + * * @type {boolean} */ set enabled(arg) { this._setValue('enabled', arg); } + /** + * Gets the enabled state of the component. + * + * @type {boolean} + */ get enabled() { return this.data.enabled; } /** - * Whether the scrollbar moves horizontally or vertically. Can be: + * Sets whether the scrollbar moves horizontally or vertically. Can be: * * - {@link ORIENTATION_HORIZONTAL}: The scrollbar animates in the horizontal axis. * - {@link ORIENTATION_VERTICAL}: The scrollbar animates in the vertical axis. @@ -83,12 +90,17 @@ class ScrollbarComponent extends Component { this._setValue('orientation', arg); } + /** + * Gets whether the scrollbar moves horizontally or vertically. + * + * @type {number} + */ get orientation() { return this.data.orientation; } /** - * The current position value of the scrollbar, in the range 0 to 1. Defaults to 0. + * Sets the current position value of the scrollbar, in the range 0 to 1. Defaults to 0. * * @type {number} */ @@ -96,13 +108,19 @@ class ScrollbarComponent extends Component { this._setValue('value', arg); } + /** + * Gets the current position value of the scrollbar. + * + * @type {number} + */ get value() { return this.data.value; } /** - * The size of the handle relative to the size of the track, in the range 0 to 1. For a vertical - * scrollbar, a value of 1 means that the handle will take up the full height of the track. + * Sets the size of the handle relative to the size of the track, in the range 0 to 1. For a + * vertical scrollbar, a value of 1 means that the handle will take up the full height of the + * track. * * @type {number} */ @@ -110,12 +128,18 @@ class ScrollbarComponent extends Component { this._setValue('handleSize', arg); } + /** + * Gets the size of the handle relative to the size of the track. + * + * @type {number} + */ get handleSize() { return this.data.handleSize; } /** - * The entity to be used as the scrollbar handle. This entity must have a Scrollbar component. + * Sets the entity to be used as the scrollbar handle. This entity must have a + * {@link ScrollbarComponent}. * * @type {import('../../../framework/entity.js').Entity} */ @@ -123,6 +147,11 @@ class ScrollbarComponent extends Component { this._setValue('handleEntity', arg); } + /** + * Gets the entity to be used as the scrollbar handle. + * + * @type {import('../../../framework/entity.js').Entity} + */ get handleEntity() { return this.data.handleEntity; } diff --git a/src/framework/components/sound/component.js b/src/framework/components/sound/component.js index bff0fd94384..4813c7b60df 100644 --- a/src/framework/components/sound/component.js +++ b/src/framework/components/sound/component.js @@ -132,8 +132,8 @@ class SoundComponent extends Component { } /** - * Determines which algorithm to use to reduce the volume of the sound as it moves away from - * the listener. Can be: + * Sets which algorithm to use to reduce the volume of the sound as it moves away from the + * listener. Can be: * * - {@link DISTANCE_LINEAR} * - {@link DISTANCE_INVERSE} @@ -148,13 +148,20 @@ class SoundComponent extends Component { this._updateSoundInstances('distanceModel', value, false); } + /** + * Gets which algorithm to use to reduce the volume of the sound as it moves away from the + * listener. + * + * @type {string} + */ get distanceModel() { return this._distanceModel; } /** - * The maximum distance from the listener at which audio falloff stops. Note the volume of the - * audio is not 0 after this distance, but just doesn't fall off anymore. Defaults to 10000. + * Sets the maximum distance from the listener at which audio falloff stops. Note that the + * volume of the audio is not 0 after this distance, but just doesn't fall off anymore. + * Defaults to 10000. * * @type {number} */ @@ -163,12 +170,17 @@ class SoundComponent extends Component { this._updateSoundInstances('maxDistance', value, false); } + /** + * Gets the maximum distance from the listener at which audio falloff stops. + * + * @type {number} + */ get maxDistance() { return this._maxDistance; } /** - * The reference distance for reducing volume as the sound source moves further from the + * Sets the reference distance for reducing volume as the sound source moves further from the * listener. Defaults to 1. * * @type {number} @@ -178,12 +190,18 @@ class SoundComponent extends Component { this._updateSoundInstances('refDistance', value, false); } + /** + * Gets the reference distance for reducing volume as the sound source moves further from the + * listener. + * + * @type {number} + */ get refDistance() { return this._refDistance; } /** - * The factor used in the falloff equation. Defaults to 1. + * Sets the factor used in the falloff equation. Defaults to 1. * * @type {number} */ @@ -192,12 +210,17 @@ class SoundComponent extends Component { this._updateSoundInstances('rollOffFactor', value, false); } + /** + * Gets the factor used in the falloff equation. + * + * @type {number} + */ get rollOffFactor() { return this._rollOffFactor; } /** - * The pitch modifier to play the audio with. Must be larger than 0.01. Defaults to 1. + * Sets the pitch modifier to play the audio with. Must be larger than 0.01. Defaults to 1. * * @type {number} */ @@ -206,12 +229,17 @@ class SoundComponent extends Component { this._updateSoundInstances('pitch', value, true); } + /** + * Gets the pitch modifier to play the audio with. + * + * @type {number} + */ get pitch() { return this._pitch; } /** - * The volume modifier to play the audio with. In range 0-1. Defaults to 1. + * Sets the volume modifier to play the audio with. In range 0-1. Defaults to 1. * * @type {number} */ @@ -220,13 +248,19 @@ class SoundComponent extends Component { this._updateSoundInstances('volume', value, true); } + /** + * Gets the volume modifier to play the audio with. + * + * @type {number} + */ get volume() { return this._volume; } /** - * If true the audio will play back at the location of the Entity in space, so the audio will - * be affected by the position of the {@link AudioListenerComponent}. Defaults to true. + * Sets whether the component plays positional sound. If true, the audio will play back at the + * location of the Entity in space, so the audio will be affected by the position of the + * {@link AudioListenerComponent}. Defaults to true. * * @type {boolean} */ @@ -262,12 +296,17 @@ class SoundComponent extends Component { } } + /** + * Gets whether the component plays positional sound. + * + * @type {boolean} + */ get positional() { return this._positional; } /** - * A dictionary that contains the {@link SoundSlot}s managed by this SoundComponent. + * Sets a dictionary that contains the {@link SoundSlot}s managed by this SoundComponent. * * @type {Object} */ @@ -301,6 +340,11 @@ class SoundComponent extends Component { this.onEnable(); } + /** + * Gets a dictionary that contains the {@link SoundSlot}s managed by this SoundComponent. + * + * @type {Object} + */ get slots() { return this._slots; } @@ -360,16 +404,16 @@ class SoundComponent extends Component { * @param {object} [options] - Settings for the slot. * @param {number} [options.volume] - The playback volume, between 0 and 1. Defaults to 1. * @param {number} [options.pitch] - The relative pitch. Defaults to 1 (plays at normal pitch). - * @param {boolean} [options.loop] - If true the sound will restart when it reaches the end. + * @param {boolean} [options.loop] - If true, the sound will restart when it reaches the end. * Defaults to false. * @param {number} [options.startTime] - The start time from which the sound will start playing. * Defaults to 0 to start at the beginning. * @param {number} [options.duration] - The duration of the sound that the slot will play * starting from startTime. Defaults to `null` which means play to end of the sound. - * @param {boolean} [options.overlap] - If true then sounds played from slot will be played + * @param {boolean} [options.overlap] - If true, then sounds played from slot will be played * independently of each other. Otherwise the slot will first stop the current sound before * starting the new one. Defaults to false. - * @param {boolean} [options.autoPlay] - If true the slot will start playing as soon as its + * @param {boolean} [options.autoPlay] - If true, the slot will start playing as soon as its * audio asset is loaded. Defaults to false. * @param {number} [options.asset] - The asset id of the audio asset that is going to be played * by this slot. diff --git a/src/framework/components/sound/slot.js b/src/framework/components/sound/slot.js index 4ac1aef2f21..38581ebc320 100644 --- a/src/framework/components/sound/slot.js +++ b/src/framework/components/sound/slot.js @@ -117,15 +117,15 @@ class SoundSlot extends EventHandler { * @param {object} [options] - Settings for the slot. * @param {number} [options.volume] - The playback volume, between 0 and 1. * @param {number} [options.pitch] - The relative pitch, default of 1, plays at normal pitch. - * @param {boolean} [options.loop] - If true the sound will restart when it reaches the end. + * @param {boolean} [options.loop] - If true, the sound will restart when it reaches the end. * @param {number} [options.startTime] - The start time from which the sound will start * playing. * @param {number} [options.duration] - The duration of the sound that the slot will play * starting from startTime. - * @param {boolean} [options.overlap] - If true then sounds played from slot will be played + * @param {boolean} [options.overlap] - If true, then sounds played from slot will be played * independently of each other. Otherwise the slot will first stop the current sound before * starting the new one. - * @param {boolean} [options.autoPlay] - If true the slot will start playing as soon as its + * @param {boolean} [options.autoPlay] - If true, the slot will start playing as soon as its * audio asset is loaded. * @param {number} [options.asset] - The asset id of the audio asset that is going to be played * by this slot. @@ -500,7 +500,7 @@ class SoundSlot extends EventHandler { } /** - * The asset id. + * Sets the asset id. * * @type {number|null} */ @@ -526,12 +526,17 @@ class SoundSlot extends EventHandler { } } + /** + * Gets the asset id. + * + * @type {number|null} + */ get asset() { return this._asset; } /** - * If true the slot will begin playing as soon as it is loaded. + * Sets whether the slot will begin playing as soon as it is loaded. * * @type {boolean} */ @@ -539,12 +544,17 @@ class SoundSlot extends EventHandler { this._autoPlay = !!value; } + /** + * Gets whether the slot will begin playing as soon as it is loaded. + * + * @type {boolean} + */ get autoPlay() { return this._autoPlay; } /** - * The duration of the sound that the slot will play starting from startTime. + * Sets the duration of the sound that the slot will play starting from startTime. * * @type {number} */ @@ -560,6 +570,11 @@ class SoundSlot extends EventHandler { } } + /** + * Gets the duration of the sound that the slot will play starting from startTime. + * + * @type {number} + */ get duration() { let assetDuration = 0; if (this._hasAsset()) { @@ -575,7 +590,7 @@ class SoundSlot extends EventHandler { } /** - * Returns true if the asset of the slot is loaded. + * Gets whether the asset of the slot is loaded. * * @type {boolean} */ @@ -591,7 +606,7 @@ class SoundSlot extends EventHandler { } /** - * Returns true if the slot is currently paused. + * Gets whether the slot is currently paused. * * @type {boolean} */ @@ -610,7 +625,7 @@ class SoundSlot extends EventHandler { } /** - * Returns true if the slot is currently playing. + * Gets whether the slot is currently playing. * * @type {boolean} */ @@ -625,7 +640,7 @@ class SoundSlot extends EventHandler { } /** - * Returns true if the slot is currently stopped. + * Gets whether the slot is currently stopped. * * @type {boolean} */ @@ -640,7 +655,7 @@ class SoundSlot extends EventHandler { } /** - * If true the slot will restart when it finishes playing. + * Sets whether the slot will restart when it finishes playing. * * @type {boolean} */ @@ -654,13 +669,18 @@ class SoundSlot extends EventHandler { } } + /** + * Gets whether the slot will restart when it finishes playing. + * + * @type {boolean} + */ get loop() { return this._loop; } /** - * If true then sounds played from slot will be played independently of each other. Otherwise - * the slot will first stop the current sound before starting the new one. + * Sets whether the sounds played from this slot will be played independently of each other. + * Otherwise, the slot will first stop the current sound before starting the new one. * * @type {boolean} */ @@ -668,12 +688,17 @@ class SoundSlot extends EventHandler { this._overlap = !!value; } + /** + * Gets whether the sounds played from this slot will be played independently of each other. + * + * @type {boolean} + */ get overlap() { return this._overlap; } /** - * The pitch modifier to play the sound with. Must be larger than 0.01. + * Sets the pitch modifier to play the sound with. Must be larger than 0.01. * * @type {number} */ @@ -689,12 +714,17 @@ class SoundSlot extends EventHandler { } } + /** + * Gets the pitch modifier to play the sound with. + * + * @type {number} + */ get pitch() { return this._pitch; } /** - * The start time from which the sound will start playing. + * Sets the start time from which the sound will start playing. * * @type {number} */ @@ -710,12 +740,17 @@ class SoundSlot extends EventHandler { } } + /** + * Gets the start time from which the sound will start playing. + * + * @type {number} + */ get startTime() { return this._startTime; } /** - * The volume modifier to play the sound with. In range 0-1. + * Sets the volume modifier to play the sound with. In range 0-1. * * @type {number} */ @@ -731,6 +766,11 @@ class SoundSlot extends EventHandler { } } + /** + * Gets the volume modifier to play the sound with. + * + * @type {number} + */ get volume() { return this._volume; } diff --git a/src/framework/components/sound/system.js b/src/framework/components/sound/system.js index 40bd79c1118..5a1a45c8024 100644 --- a/src/framework/components/sound/system.js +++ b/src/framework/components/sound/system.js @@ -46,8 +46,8 @@ class SoundComponentSystem extends ComponentSystem { } /** - * Sets / gets the volume for the entire Sound system. All sounds will have their volume - * multiplied by this value. Valid between [0, 1]. + * Sets the volume for the entire Sound system. All sounds will have their volume multiplied by + * this value. Valid between [0, 1]. * * @type {number} */ @@ -55,6 +55,11 @@ class SoundComponentSystem extends ComponentSystem { this.manager.volume = volume; } + /** + * Gets the volume for the entire Sound system. + * + * @type {number} + */ get volume() { return this.manager.volume; } diff --git a/src/framework/components/sprite/component.js b/src/framework/components/sprite/component.js index 057c5043975..d3f6c26fe17 100644 --- a/src/framework/components/sprite/component.js +++ b/src/framework/components/sprite/component.js @@ -181,7 +181,7 @@ class SpriteComponent extends Component { } /** - * The type of the SpriteComponent. Can be: + * Sets the type of the SpriteComponent. Can be: * * - {@link SPRITETYPE_SIMPLE}: The component renders a single frame from a sprite asset. * - {@link SPRITETYPE_ANIMATED}: The component can play sprite animation clips. @@ -224,13 +224,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the type of the SpriteComponent. + * + * @type {string} + */ get type() { return this._type; } /** - * The frame counter of the sprite. Specifies which frame from the current sprite asset to - * render. + * Sets which frame from the current sprite asset to render. * * @type {number} */ @@ -238,12 +242,17 @@ class SpriteComponent extends Component { this._currentClip.frame = value; } + /** + * Gets which frame from the current sprite asset to render. + * + * @type {number} + */ get frame() { return this._currentClip.frame; } /** - * The asset id or the {@link Asset} of the sprite to render. Only works for + * Sets the asset id or the {@link Asset} of the sprite to render. Only works for * {@link SPRITETYPE_SIMPLE} sprites. * * @type {number|import('../../asset/asset.js').Asset} @@ -252,12 +261,17 @@ class SpriteComponent extends Component { this._defaultClip.spriteAsset = value; } + /** + * Gets the asset id or the {@link Asset} of the sprite to render. + * + * @type {number|import('../../asset/asset.js').Asset} + */ get spriteAsset() { return this._defaultClip._spriteAsset; } /** - * The current sprite. + * Sets the current sprite. * * @type {import('../../../scene/sprite.js').Sprite} */ @@ -265,6 +279,11 @@ class SpriteComponent extends Component { this._currentClip.sprite = value; } + /** + * Gets the current sprite. + * + * @type {import('../../../scene/sprite.js').Sprite} + */ get sprite() { return this._currentClip.sprite; } @@ -282,7 +301,7 @@ class SpriteComponent extends Component { } /** - * The color tint of the sprite. + * Sets the color tint of the sprite. * * @type {Color} */ @@ -299,12 +318,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the color tint of the sprite. + * + * @type {Color} + */ get color() { return this._color; } /** - * The opacity of the sprite. + * Sets the opacity of the sprite. * * @type {number} */ @@ -315,12 +339,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the opacity of the sprite. + * + * @type {number} + */ get opacity() { return this._color.a; } /** - * A dictionary that contains {@link SpriteAnimationClip}s. + * Sets the dictionary that contains {@link SpriteAnimationClip}s. * * @type {Object} */ @@ -376,12 +405,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the dictionary that contains {@link SpriteAnimationClip}s. + * + * @type {Object} + */ get clips() { return this._clips; } /** - * The current clip being played. + * Gets the current clip being played. * * @type {SpriteAnimationClip} */ @@ -390,7 +424,7 @@ class SpriteComponent extends Component { } /** - * A global speed modifier used when playing sprite animation clips. + * Sets the global speed modifier used when playing sprite animation clips. * * @type {number} */ @@ -398,12 +432,17 @@ class SpriteComponent extends Component { this._speed = value; } + /** + * Gets the global speed modifier used when playing sprite animation clips. + * + * @type {number} + */ get speed() { return this._speed; } /** - * Flip the X axis when rendering a sprite. + * Sets whether to flip the X axis when rendering a sprite. * * @type {boolean} */ @@ -414,12 +453,17 @@ class SpriteComponent extends Component { this._updateTransform(); } + /** + * Gets whether to flip the X axis when rendering a sprite. + * + * @type {boolean} + */ get flipX() { return this._flipX; } /** - * Flip the Y axis when rendering a sprite. + * Sets whether to flip the Y axis when rendering a sprite. * * @type {boolean} */ @@ -430,13 +474,18 @@ class SpriteComponent extends Component { this._updateTransform(); } + /** + * Gets whether to flip the Y axis when rendering a sprite. + * + * @type {boolean} + */ get flipY() { return this._flipY; } /** - * The width of the sprite when rendering using 9-Slicing. The width and height are only used - * when the render mode of the sprite asset is Sliced or Tiled. + * Sets the width of the sprite when rendering using 9-Slicing. The width and height are only + * used when the render mode of the sprite asset is Sliced or Tiled. * * @type {number} */ @@ -451,13 +500,18 @@ class SpriteComponent extends Component { } } + /** + * Gets the width of the sprite when rendering using 9-Slicing. + * + * @type {number} + */ get width() { return this._width; } /** - * The height of the sprite when rendering using 9-Slicing. The width and height are only used - * when the render mode of the sprite asset is Sliced or Tiled. + * Sets the height of the sprite when rendering using 9-Slicing. The width and height are only + * used when the render mode of the sprite asset is Sliced or Tiled. * * @type {number} */ @@ -472,12 +526,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the height of the sprite when rendering using 9-Slicing. + * + * @type {number} + */ get height() { return this._height; } /** - * Assign sprite to a specific batch group (see {@link BatchGroup}). Default is -1 (no group). + * Sets the batch group for the sprite (see {@link BatchGroup}). Default is -1 (no group). * * @type {number} */ @@ -503,12 +562,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the batch group for the sprite. + * + * @type {number} + */ get batchGroupId() { return this._batchGroupId; } /** - * The name of the clip to play automatically when the component is enabled and the clip exists. + * Sets the name of the clip to play automatically when the component is enabled. * * @type {string} */ @@ -517,14 +581,19 @@ class SpriteComponent extends Component { this._tryAutoPlay(); } + /** + * Gets the name of the clip to play automatically when the component is enabled. + * + * @type {string} + */ get autoPlayClip() { return this._autoPlayClip; } /** - * The draw order of the component. A higher value means that the component will be rendered on - * top of other components in the same layer. This is not used unless the layer's sort order is - * set to {@link SORTMODE_MANUAL}. + * Sets the draw order of the component. A higher value means that the component will be + * rendered on top of other components in the same layer. This is not used unless the layer's + * sort order is set to {@link SORTMODE_MANUAL}. * * @type {number} */ @@ -535,12 +604,17 @@ class SpriteComponent extends Component { } } + /** + * Gets the draw order of the component. + * + * @type {number} + */ get drawOrder() { return this._drawOrder; } /** - * An array of layer IDs ({@link Layer#id}) to which this sprite should belong. + * Sets the array of layer IDs ({@link Layer#id}) to which this sprite should belong. * * @type {number[]} */ @@ -561,6 +635,11 @@ class SpriteComponent extends Component { } } + /** + * Gets the array of layer IDs ({@link Layer#id}) to which this sprite belongs. + * + * @type {number[]} + */ get layers() { return this._layers; } diff --git a/src/framework/components/sprite/sprite-animation-clip.js b/src/framework/components/sprite/sprite-animation-clip.js index f62e602dab7..b291ecba90d 100644 --- a/src/framework/components/sprite/sprite-animation-clip.js +++ b/src/framework/components/sprite/sprite-animation-clip.js @@ -110,7 +110,7 @@ class SpriteAnimationClip extends EventHandler { } /** - * The total duration of the animation in seconds. + * Gets the total duration of the animation in seconds. * * @type {number} */ @@ -123,7 +123,7 @@ class SpriteAnimationClip extends EventHandler { } /** - * The index of the frame of the {@link Sprite} currently being rendered. + * Sets the index of the frame of the {@link Sprite} currently being rendered. * * @type {number} */ @@ -135,12 +135,17 @@ class SpriteAnimationClip extends EventHandler { this._setTime(this._frame / fps); } + /** + * Gets the index of the frame of the {@link Sprite} currently being rendered. + * + * @type {number} + */ get frame() { return this._frame; } /** - * Whether the animation is currently paused. + * Sets whether the animation is currently paused. * * @type {boolean} */ @@ -149,7 +154,7 @@ class SpriteAnimationClip extends EventHandler { } /** - * Whether the animation is currently playing. + * Sets whether the animation is currently playing. * * @type {boolean} */ @@ -158,7 +163,7 @@ class SpriteAnimationClip extends EventHandler { } /** - * The current sprite used to play the animation. + * Sets the current sprite used to play the animation. * * @type {import('../../../scene/sprite.js').Sprite} */ @@ -228,12 +233,17 @@ class SpriteAnimationClip extends EventHandler { } } + /** + * Gets the current sprite used to play the animation. + * + * @type {import('../../../scene/sprite.js').Sprite} + */ get sprite() { return this._sprite; } /** - * The id of the sprite asset used to play the animation. + * Sets the id of the sprite asset used to play the animation. * * @type {number} */ @@ -271,12 +281,17 @@ class SpriteAnimationClip extends EventHandler { } } + /** + * Gets the id of the sprite asset used to play the animation. + * + * @type {number} + */ get spriteAsset() { return this._spriteAsset; } /** - * The current time of the animation in seconds. + * Sets the current time of the animation in seconds. * * @type {number} */ @@ -290,6 +305,11 @@ class SpriteAnimationClip extends EventHandler { } } + /** + * Gets the current time of the animation in seconds. + * + * @type {number} + */ get time() { return this._time; } diff --git a/src/framework/handlers/handler.js b/src/framework/handlers/handler.js index ce7657bf622..36c2db15051 100644 --- a/src/framework/handlers/handler.js +++ b/src/framework/handlers/handler.js @@ -37,7 +37,7 @@ class ResourceHandler { } /** - * The number of times to retry a failed request for the resource. + * Sets the number of times to retry a failed request for the resource. * * @type {number} */ @@ -45,6 +45,11 @@ class ResourceHandler { this._maxRetries = value; } + /** + * Gets the number of times to retry a failed request for the resource. + * + * @type {number} + */ get maxRetries() { return this._maxRetries; } diff --git a/src/framework/i18n/i18n.js b/src/framework/i18n/i18n.js index 757b70b45f0..18868cab4e2 100644 --- a/src/framework/i18n/i18n.js +++ b/src/framework/i18n/i18n.js @@ -38,9 +38,9 @@ class I18n extends EventHandler { } /** - * An array of asset ids or assets that contain localization data in the expected format. I18n - * will automatically load translations from these assets as the assets are loaded and it will - * also automatically unload translations if the assets get removed or unloaded at runtime. + * Sets the array of asset ids or assets that contain localization data in the expected format. + * I18n will automatically load translations from these assets as the assets are loaded and it + * will also automatically unload translations if the assets get removed or unloaded at runtime. * * @type {number[]|Asset[]} */ @@ -82,13 +82,18 @@ class I18n extends EventHandler { } } + /** + * Gets the array of asset ids that contain localization data in the expected format. + * + * @type {number[]|Asset[]} + */ get assets() { return this._assets; } /** - * The current locale for example "en-US". Changing the locale will raise an event which will - * cause localized Text Elements to change language to the new locale. + * Sets the current locale. For example, "en-US". Changing the locale will raise an event which + * will cause localized Text Elements to change language to the new locale. * * @type {string} */ @@ -119,6 +124,11 @@ class I18n extends EventHandler { this.fire('set:locale', value, old); } + /** + * Gets the current locale. + * + * @type {string} + */ get locale() { return this._locale; } diff --git a/src/framework/script/script-type.js b/src/framework/script/script-type.js index 3a1ff14a3d6..97c49855b31 100644 --- a/src/framework/script/script-type.js +++ b/src/framework/script/script-type.js @@ -190,11 +190,11 @@ class ScriptType extends EventHandler { } /** - * True if the instance of this type is in running state. False when script is not running, - * because the Entity or any of its parents are disabled or the {@link ScriptComponent} is - * disabled or the Script Instance is disabled. When disabled no update methods will be called - * on each tick. initialize and postInitialize methods will run once when the script instance - * is in `enabled` state during app tick. + * Sets the enabled state for this ScriptType. False when script is not running, because the + * Entity or any of its parents are disabled or the {@link ScriptComponent} is disabled or the + * Script Instance is disabled. When disabled no update methods will be called on each tick. + * initialize and postInitialize methods will run once when the script instance is in `enabled` + * state during app tick. * * @type {boolean} */ @@ -230,6 +230,11 @@ class ScriptType extends EventHandler { } } + /** + * Gets the enabled state for this ScriptType. + * + * @type {boolean} + */ get enabled() { return this._enabled && !this._destroyed && this.entity.script.enabled && this.entity.enabled; } diff --git a/src/framework/utils/entity-reference.js b/src/framework/utils/entity-reference.js index d8a45310991..523dda80a30 100644 --- a/src/framework/utils/entity-reference.js +++ b/src/framework/utils/entity-reference.js @@ -220,7 +220,7 @@ class EntityReference extends EventHandler { _onSetEntity(name, oldValue, newValue) { if (newValue instanceof Entity) { this._updateEntityReference(); - } else { + } else { if (newValue !== null && newValue !== undefined && typeof newValue !== 'string') { console.warn("Entity field `" + this._entityPropertyName + "` was set to unexpected type '" + (typeof newValue) + "'"); return; diff --git a/src/framework/xr/xr-dom-overlay.js b/src/framework/xr/xr-dom-overlay.js index f011d0251e3..8d3e1757c9a 100644 --- a/src/framework/xr/xr-dom-overlay.js +++ b/src/framework/xr/xr-dom-overlay.js @@ -93,8 +93,8 @@ class XrDomOverlay { } /** - * The DOM element to be used as the root for DOM Overlay. Can be changed only when XR session - * is not running. + * Sets the DOM element to be used as the root for DOM Overlay. Can be changed only when XR + * session is not running. * * @type {Element|null} * @example @@ -108,6 +108,11 @@ class XrDomOverlay { this._root = value; } + /** + * Gets the DOM element to be used as the root for DOM Overlay. + * + * @type {Element|null} + */ get root() { return this._root; } diff --git a/src/framework/xr/xr-input-source.js b/src/framework/xr/xr-input-source.js index 963c7486f6f..0c14e8a24e3 100644 --- a/src/framework/xr/xr-input-source.js +++ b/src/framework/xr/xr-input-source.js @@ -426,7 +426,7 @@ class XrInputSource extends EventHandler { } /** - * Set to true to allow input source to interact with Element components. Defaults to true. + * Sets whether the input source can interact with {@link ElementComponent}s. Defaults to true. * * @type {boolean} */ @@ -440,6 +440,11 @@ class XrInputSource extends EventHandler { this._elementEntity = null; } + /** + * Gets whether the input source can interact with {@link ElementComponent}s. + * + * @type {boolean} + */ get elementInput() { return this._elementInput; } diff --git a/src/framework/xr/xr-tracked-image.js b/src/framework/xr/xr-tracked-image.js index d0e416c5a27..460196e2046 100644 --- a/src/framework/xr/xr-tracked-image.js +++ b/src/framework/xr/xr-tracked-image.js @@ -132,6 +132,11 @@ class XrTrackedImage extends EventHandler { this._width = value; } + /** + * Get the width (in meters) of image in real world. + * + * @type {number} + */ get width() { return this._width; } diff --git a/src/platform/graphics/blend-state.js b/src/platform/graphics/blend-state.js index 2f35263a376..0c6df787ba3 100644 --- a/src/platform/graphics/blend-state.js +++ b/src/platform/graphics/blend-state.js @@ -33,7 +33,7 @@ const allWriteShift = redWriteShift; */ class BlendState { /** - * Bitfield representing the blend state for render target 0. + * Bit field representing the blend state for render target 0. * * @private */ @@ -101,7 +101,7 @@ class BlendState { } /** - * Enables or disables blending. + * Sets whether blending is enabled. * * @type {boolean} */ @@ -109,6 +109,11 @@ class BlendState { this.target0 = BitPacking.set(this.target0, value ? 1 : 0, blendShift); } + /** + * Gets whether blending is enabled. + * + * @type {boolean} + */ get blend() { return BitPacking.all(this.target0, blendShift); } diff --git a/src/platform/graphics/depth-state.js b/src/platform/graphics/depth-state.js index a2bd444c7e5..cb32fd4a670 100644 --- a/src/platform/graphics/depth-state.js +++ b/src/platform/graphics/depth-state.js @@ -25,7 +25,7 @@ const writeShift = 3; // 03 - 03 (1bit) */ class DepthState { /** - * Bitfield representing the depth state. + * Bit field representing the depth state. * * @private */ @@ -59,9 +59,10 @@ class DepthState { } /** - * If true, a shader fragment is only written to the current render target if it passes the depth - * test. If false, it is written regardless of what is in the depth buffer. Note that when depth - * testing is disabled, writes to the depth buffer are also disabled. Defaults to true. + * Sets whether depth testing is performed. If true, a shader fragment is only written to the + * current render target if it passes the depth test. If false, it is written regardless of + * what is in the depth buffer. Note that when depth testing is disabled, writes to the depth + * buffer are also disabled. Defaults to true. * * @type {boolean} */ @@ -70,13 +71,18 @@ class DepthState { this.updateKey(); } + /** + * Gets whether depth testing is performed. + * + * @type {boolean} + */ get test() { return this.func !== FUNC_ALWAYS; } /** - * If true, shader write a depth value to the depth buffer of the currently active render - * target. If false, no depth value is written. + * Sets whether depth writing is performed. If true, shader write a depth value to the depth + * buffer of the currently active render target. If false, no depth value is written. * * @type {boolean} */ @@ -85,13 +91,18 @@ class DepthState { this.updateKey(); } + /** + * Gets whether depth writing is performed. + * + * @type {boolean} + */ get write() { return BitPacking.all(this.data, writeShift); } /** - * Controls how the depth of the fragment is compared against the current depth contained in - * the depth buffer. Can be: + * Sets the depth testing function. Controls how the depth of the fragment is compared against + * the current depth contained in the depth buffer. Can be: * * - {@link FUNC_NEVER}: don't draw * - {@link FUNC_LESS}: draw if new depth < depth buffer @@ -109,14 +120,19 @@ class DepthState { this.updateKey(); } + /** + * Gets the depth testing function. + * + * @type {number} + */ get func() { return BitPacking.get(this.data, funcShift, funcMask); } /** - * Constant depth bias added to each fragment's depth. Useful for decals to prevent z-fighting. - * Typically a small negative value (-0.1) is used to render the mesh slightly closer to the - * camera. Defaults to 0. + * Sets the constant depth bias added to each fragment's depth. Useful for decals to prevent + * z-fighting. Typically a small negative value (-0.1) is used to render the mesh slightly + * closer to the camera. Defaults to 0. * * @type {number} */ @@ -125,12 +141,17 @@ class DepthState { this.updateKey(); } + /** + * Gets the constant depth bias added to each fragment's depth. + * + * @type {number} + */ get depthBias() { return this._depthBias; } /** - * Depth bias that scales with the fragment’s slope. Defaults to 0. + * Sets the depth bias that scales with the fragment's slope. Defaults to 0. * * @type {number} */ @@ -139,6 +160,11 @@ class DepthState { this.updateKey(); } + /** + * Gets the depth bias that scales with the fragment's slope. + * + * @type {number} + */ get depthBiasSlope() { return this._depthBiasSlope; } diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index 5e63c803c3d..c8fb6ddf09d 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -808,7 +808,7 @@ class GraphicsDevice extends EventHandler { } /** - * Fullscreen mode. + * Sets whether the device is currently in fullscreen mode. * * @type {boolean} */ @@ -816,13 +816,18 @@ class GraphicsDevice extends EventHandler { Debug.error("GraphicsDevice.fullscreen is not implemented on current device."); } + /** + * Gets whether the device is currently in fullscreen mode. + * + * @type {boolean} + */ get fullscreen() { Debug.error("GraphicsDevice.fullscreen is not implemented on current device."); return false; } /** - * Maximum pixel ratio. + * Sets the maximum pixel ratio. * * @type {number} */ @@ -830,12 +835,21 @@ class GraphicsDevice extends EventHandler { this._maxPixelRatio = ratio; } + /** + * Gets the maximum pixel ratio. + * + * @type {number} + */ get maxPixelRatio() { return this._maxPixelRatio; } /** - * The type of the device. Can be one of pc.DEVICETYPE_WEBGL1, pc.DEVICETYPE_WEBGL2 or pc.DEVICETYPE_WEBGPU. + * Gets the type of the device. Can be: + * + * - {@link DEVICETYPE_WEBGL1} + * - {@link DEVICETYPE_WEBGL2} + * - {@link DEVICETYPE_WEBGPU} * * @type {import('./constants.js').DEVICETYPE_WEBGL1 | import('./constants.js').DEVICETYPE_WEBGL2 | import('./constants.js').DEVICETYPE_WEBGPU} */ diff --git a/src/platform/graphics/render-target.js b/src/platform/graphics/render-target.js index 1c5dc337196..5f7baf194e0 100644 --- a/src/platform/graphics/render-target.js +++ b/src/platform/graphics/render-target.js @@ -389,8 +389,8 @@ class RenderTarget { * anti-aliasing samples must match. Depth buffer can only be copied on WebGL 2.0. * * @param {RenderTarget} source - Source render target to copy from. - * @param {boolean} [color] - If true will copy the color buffer. Defaults to false. - * @param {boolean} [depth] - If true will copy the depth buffer. Defaults to false. + * @param {boolean} [color] - If true, will copy the color buffer. Defaults to false. + * @param {boolean} [depth] - If true, will copy the depth buffer. Defaults to false. * @returns {boolean} True if the copy was successful, false otherwise. */ copy(source, color, depth) { diff --git a/src/platform/graphics/stencil-parameters.js b/src/platform/graphics/stencil-parameters.js index 93732f9f06c..13924e10319 100644 --- a/src/platform/graphics/stencil-parameters.js +++ b/src/platform/graphics/stencil-parameters.js @@ -64,8 +64,8 @@ class StencilParameters { _key; /** - * A comparison function that decides if the pixel should be written, based on the current - * stencil buffer value, reference value, and mask value. Can be: + * Sets the comparison function that decides if the pixel should be written, based on the + * current stencil buffer value, reference value, and mask value. Can be: * * - {@link FUNC_NEVER}: never pass * - {@link FUNC_LESS}: pass if (ref & mask) < (stencil & mask) @@ -83,12 +83,17 @@ class StencilParameters { this._dirty = true; } + /** + * Sets the comparison function that decides if the pixel should be written. + * + * @type {number} + */ get func() { return this._func; } /** - * Sets stencil test reference value used in comparisons. + * Sets the stencil test reference value used in comparisons. * * @type {number} */ @@ -97,12 +102,17 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the stencil test reference value used in comparisons. + * + * @type {number} + */ get ref() { return this._ref; } /** - * Operation to perform if stencil test is failed. Can be: + * Sets the operation to perform if stencil test is failed. Can be: * * - {@link STENCILOP_KEEP}: don't change the stencil buffer value * - {@link STENCILOP_ZERO}: set value to zero @@ -122,12 +132,17 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the operation to perform if stencil test is failed. + * + * @type {number} + */ get fail() { return this._fail; } /** - * Operation to perform if depth test is failed. Accepts the same values as `fail`. + * Sets the operation to perform if depth test is failed. Accepts the same values as `fail`. * * @type {number} */ @@ -136,13 +151,18 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the operation to perform if depth test is failed. + * + * @type {number} + */ get zfail() { return this._zfail; } /** - * Operation to perform if both stencil and depth test are passed. Accepts the same values as - * `fail`. + * Sets the operation to perform if both stencil and depth test are passed. Accepts the same + * values as `fail`. * * @type {number} */ @@ -151,12 +171,17 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the operation to perform if both stencil and depth test are passed. + * + * @type {number} + */ get zpass() { return this._zpass; } /** - * Mask applied to stencil buffer value and reference value before comparison. + * Sets the mask applied to stencil buffer value and reference value before comparison. * * @type {number} */ @@ -165,12 +190,17 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the mask applied to stencil buffer value and reference value before comparison. + * + * @type {number} + */ get readMask() { return this._readMask; } /** - * A bit mask applied to the stencil value, when written. + * Sets the bit mask applied to the stencil value when written. * * @type {number} */ @@ -179,6 +209,11 @@ class StencilParameters { this._dirty = true; } + /** + * Gets the bit mask applied to the stencil value when written. + * + * @type {number} + */ get writeMask() { return this._writeMask; } diff --git a/src/platform/graphics/texture.js b/src/platform/graphics/texture.js index 19ddb5a0bf2..553a8edcd8c 100644 --- a/src/platform/graphics/texture.js +++ b/src/platform/graphics/texture.js @@ -395,7 +395,7 @@ class Texture { } /** - * The minification filter to be applied to the texture. Can be: + * Sets the minification filter to be applied to the texture. Can be: * * - {@link FILTER_NEAREST} * - {@link FILTER_LINEAR} @@ -417,12 +417,17 @@ class Texture { } } + /** + * Gets the minification filter to be applied to the texture. + * + * @type {number} + */ get minFilter() { return this._minFilter; } /** - * The magnification filter to be applied to the texture. Can be: + * Sets the magnification filter to be applied to the texture. Can be: * * - {@link FILTER_NEAREST} * - {@link FILTER_LINEAR} @@ -440,12 +445,17 @@ class Texture { } } + /** + * Gets the magnification filter to be applied to the texture. + * + * @type {number} + */ get magFilter() { return this._magFilter; } /** - * The addressing mode to be applied to the texture horizontally. Can be: + * Sets the addressing mode to be applied to the texture horizontally. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} @@ -460,12 +470,17 @@ class Texture { } } + /** + * Gets the addressing mode to be applied to the texture horizontally. + * + * @type {number} + */ get addressU() { return this._addressU; } /** - * The addressing mode to be applied to the texture vertically. Can be: + * Sets the addressing mode to be applied to the texture vertically. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} @@ -480,12 +495,17 @@ class Texture { } } + /** + * Gets the addressing mode to be applied to the texture vertically. + * + * @type {number} + */ get addressV() { return this._addressV; } /** - * The addressing mode to be applied to the 3D texture depth (not supported on WebGL1). Can be: + * Sets the addressing mode to be applied to the 3D texture depth. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} @@ -505,6 +525,11 @@ class Texture { } } + /** + * Gets the addressing mode to be applied to the 3D texture depth. + * + * @type {number} + */ get addressW() { return this._addressW; } @@ -523,12 +548,17 @@ class Texture { } } + /** + * Gets whether you can get filtered results of comparison using texture() in your shader. + * + * @type {boolean} + */ get compareOnRead() { return this._compareOnRead; } /** - * Comparison function when compareOnRead is enabled (not supported on WebGL1). Possible values: + * Sets the comparison function when compareOnRead is enabled. Possible values: * * - {@link FUNC_LESS} * - {@link FUNC_LESSEQUAL} @@ -546,13 +576,18 @@ class Texture { } } + /** + * Sets the comparison function when compareOnRead is enabled. + * + * @type {number} + */ get compareFunc() { return this._compareFunc; } /** - * Integer value specifying the level of anisotropic to apply to the texture ranging from 1 (no - * anisotropic filtering) to the {@link GraphicsDevice} property maxAnisotropy. + * Sets the integer value specifying the level of anisotropy to apply to the texture ranging + * from 1 (no anisotropic filtering) to the {@link GraphicsDevice} property maxAnisotropy. * * @type {number} */ @@ -563,12 +598,17 @@ class Texture { } } + /** + * Gets the integer value specifying the level of anisotropy to apply to the texture. + * + * @type {number} + */ get anisotropy() { return this._anisotropy; } /** - * Defines if texture should generate/upload mipmaps if possible. + * Sets whether the texture should generate/upload mipmaps. * * @type {boolean} */ @@ -587,6 +627,11 @@ class Texture { } } + /** + * Gets whether the texture should generate/upload mipmaps. + * + * @type {boolean} + */ get mipmaps() { return this._mipmaps; } @@ -703,7 +748,7 @@ class Texture { } /** - * Specifies whether the texture should be flipped in the Y-direction. Only affects textures + * Sets whether the texture should be flipped in the Y-direction. Only affects textures * with a source that is an image, canvas or video element. Does not affect cubemaps, * compressed textures or textures set from raw pixel data. Defaults to true. * @@ -716,6 +761,11 @@ class Texture { } } + /** + * Gets whether the texture should be flipped in the Y-direction. + * + * @type {boolean} + */ get flipY() { return this._flipY; } diff --git a/src/platform/graphics/webgl/webgl-graphics-device.js b/src/platform/graphics/webgl/webgl-graphics-device.js index 42929b900a8..ef9f0c96895 100644 --- a/src/platform/graphics/webgl/webgl-graphics-device.js +++ b/src/platform/graphics/webgl/webgl-graphics-device.js @@ -1027,7 +1027,6 @@ class WebglGraphicsDevice extends GraphicsDevice { return null; } - /** @ignore */ get extDisjointTimerQuery() { // lazy evaluation as this is not typically used if (!this._extDisjointTimerQuery) { @@ -1397,8 +1396,8 @@ class WebglGraphicsDevice extends GraphicsDevice { * * @param {RenderTarget} [source] - The source render target. Defaults to frame buffer. * @param {RenderTarget} [dest] - The destination render target. Defaults to frame buffer. - * @param {boolean} [color] - If true will copy the color buffer. Defaults to false. - * @param {boolean} [depth] - If true will copy the depth buffer. Defaults to false. + * @param {boolean} [color] - If true, will copy the color buffer. Defaults to false. + * @param {boolean} [depth] - If true, will copy the depth buffer. Defaults to false. * @returns {boolean} True if the copy was successful, false otherwise. */ copyRenderTarget(source, dest, color, depth) { @@ -2798,7 +2797,7 @@ class WebglGraphicsDevice extends GraphicsDevice { } /** - * Fullscreen mode. + * Sets whether the device is currently in fullscreen mode. * * @type {boolean} */ @@ -2811,6 +2810,11 @@ class WebglGraphicsDevice extends GraphicsDevice { } } + /** + * Gets whether the device is currently in fullscreen mode. + * + * @type {boolean} + */ get fullscreen() { return !!document.fullscreenElement; } diff --git a/src/platform/graphics/webgpu/webgpu-graphics-device.js b/src/platform/graphics/webgpu/webgpu-graphics-device.js index df26030e6cf..46a3e9fda0a 100644 --- a/src/platform/graphics/webgpu/webgpu-graphics-device.js +++ b/src/platform/graphics/webgpu/webgpu-graphics-device.js @@ -977,8 +977,8 @@ class WebgpuGraphicsDevice extends GraphicsDevice { * * @param {RenderTarget} [source] - The source render target. Defaults to frame buffer. * @param {RenderTarget} [dest] - The destination render target. Defaults to frame buffer. - * @param {boolean} [color] - If true will copy the color buffer. Defaults to false. - * @param {boolean} [depth] - If true will copy the depth buffer. Defaults to false. + * @param {boolean} [color] - If true, will copy the color buffer. Defaults to false. + * @param {boolean} [depth] - If true, will copy the depth buffer. Defaults to false. * @returns {boolean} True if the copy was successful, false otherwise. */ copyRenderTarget(source, dest, color, depth) { diff --git a/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js b/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js index 6be0eda5a35..a5a27a2ba2c 100644 --- a/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js +++ b/src/platform/graphics/webgpu/webgpu-vertex-buffer-layout.js @@ -63,7 +63,7 @@ class WebgpuVertexBufferLayout { */ create(vertexFormat0, vertexFormat1) { - // type {GPUVertexBufferLayout[]} + // type {GPUVertexBufferLayout[]} const layout = []; // Note: If the VertexFormat is interleaved, we use a single vertex buffer with multiple diff --git a/src/platform/input/game-pads.js b/src/platform/input/game-pads.js index 7fba1d1593c..3d9703c5529 100644 --- a/src/platform/input/game-pads.js +++ b/src/platform/input/game-pads.js @@ -460,7 +460,7 @@ class GamePad { } /** - * Whether the gamepad is connected. + * Gets whether the gamepad is connected. * * @type {boolean} */ @@ -621,7 +621,7 @@ class GamePad { } /** - * The values from analog axes present on the GamePad. Values are between -1 and 1. + * Gets the values from analog axes present on the GamePad. Values are between -1 and 1. * * @type {number[]} */ @@ -630,7 +630,7 @@ class GamePad { } /** - * The buttons present on the GamePad. + * Gets the buttons present on the GamePad. * * @type {GamePadButton[]} */ @@ -844,7 +844,7 @@ class GamePads extends EventHandler { } /** - * Threshold for axes to return values. Must be between 0 and 1. + * Sets the threshold for axes to return values. Must be between 0 and 1. * * @type {number} * @ignore @@ -853,12 +853,18 @@ class GamePads extends EventHandler { deadZone = value; } + /** + * Gets the threshold for axes to return values. + * + * @type {number} + * @ignore + */ get deadZone() { return deadZone; } /** - * The list of previous buttons states. + * Gets the list of previous button states. * * @type {boolean[][]} * @ignore diff --git a/src/platform/sound/instance.js b/src/platform/sound/instance.js index c31bbe333a9..fd41dfb837c 100644 --- a/src/platform/sound/instance.js +++ b/src/platform/sound/instance.js @@ -299,8 +299,8 @@ class SoundInstance extends EventHandler { } /** - * Gets or sets the current time of the sound that is playing. If the value provided is bigger - * than the duration of the instance it will wrap from the beginning. + * Sets the current time of the sound that is playing. If the value provided is bigger than the + * duration of the instance it will wrap from the beginning. * * @type {number} */ @@ -326,6 +326,11 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the current time of the sound that is playing. + * + * @type {number} + */ get currentTime() { // if the user has set the currentTime and we have not used it yet // then just return that @@ -351,7 +356,7 @@ class SoundInstance extends EventHandler { } /** - * The duration of the sound that the instance will play starting from startTime. + * Sets the duration of the sound that the instance will play starting from startTime. * * @type {number} */ @@ -366,6 +371,11 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the duration of the sound that the instance will play starting from startTime. + * + * @type {number} + */ get duration() { if (!this._sound) { return 0; @@ -377,7 +387,7 @@ class SoundInstance extends EventHandler { } /** - * Returns true if the instance is currently paused. + * Gets whether the instance is currently paused. * * @type {boolean} */ @@ -386,7 +396,7 @@ class SoundInstance extends EventHandler { } /** - * Returns true if the instance is currently playing. + * Gets whether the instance is currently playing. * * @type {boolean} */ @@ -395,7 +405,7 @@ class SoundInstance extends EventHandler { } /** - * Returns true if the instance is currently stopped. + * Gets whether the instance is currently stopped. * * @type {boolean} */ @@ -404,7 +414,7 @@ class SoundInstance extends EventHandler { } /** - * Returns true if the instance is currently suspended because the window is not focused. + * Gets whether the instance is currently suspended because the window is not focused. * * @type {boolean} */ @@ -413,7 +423,7 @@ class SoundInstance extends EventHandler { } /** - * If true the instance will restart when it finishes playing. + * Sets whether the instance will restart when it finishes playing. * * @type {boolean} */ @@ -424,12 +434,17 @@ class SoundInstance extends EventHandler { } } + /** + * Gets whether the instance will restart when it finishes playing. + * + * @type {boolean} + */ get loop() { return this._loop; } /** - * The pitch modifier to play the sound with. Must be larger than 0.01. + * Sets the pitch modifier to play the sound with. Must be larger than 0.01. * * @type {number} */ @@ -446,12 +461,17 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the pitch modifier to play the sound with. + * + * @type {number} + */ get pitch() { return this._pitch; } /** - * The sound resource that the instance will play. + * Sets the sound resource that the instance will play. * * @type {import('./sound.js').Sound} */ @@ -465,12 +485,17 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the sound resource that the instance will play. + * + * @type {import('./sound.js').Sound} + */ get sound() { return this._sound; } /** - * The start time from which the sound will start playing. + * Sets the start time from which the sound will start playing. * * @type {number} */ @@ -485,12 +510,17 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the start time from which the sound will start playing. + * + * @type {number} + */ get startTime() { return this._startTime; } /** - * The volume modifier to play the sound with. In range 0-1. + * Sets the volume modifier to play the sound with. In range 0-1. * * @type {number} */ @@ -502,6 +532,11 @@ class SoundInstance extends EventHandler { } } + /** + * Gets the volume modifier to play the sound with. In range 0-1. + * + * @type {number} + */ get volume() { return this._volume; } diff --git a/src/platform/sound/instance3d.js b/src/platform/sound/instance3d.js index 006d3d3ab60..a3d8d8d41e2 100644 --- a/src/platform/sound/instance3d.js +++ b/src/platform/sound/instance3d.js @@ -86,7 +86,7 @@ class SoundInstance3d extends SoundInstance { } /** - * The position of the sound in 3D space. + * Sets the position of the sound in 3D space. * * @type {Vec3} */ @@ -102,17 +102,15 @@ class SoundInstance3d extends SoundInstance { } } - get position() { - return this._position; - } - /** - * The velocity of the sound. + * Gets the position of the sound in 3D space. * * @type {Vec3} - * @deprecated - * @ignore */ + get position() { + return this._position; + } + set velocity(velocity) { Debug.warn('SoundInstance3d#velocity is not implemented.'); this._velocity.copy(velocity); @@ -124,8 +122,8 @@ class SoundInstance3d extends SoundInstance { } /** - * The maximum distance from the listener at which audio falloff stops. Note the volume of the - * audio is not 0 after this distance, but just doesn't fall off anymore. + * Sets the maximum distance from the listener at which audio falloff stops. Note that the + * volume of the audio is not 0 after this distance, but just doesn't fall off anymore. * * @type {number} */ @@ -133,12 +131,17 @@ class SoundInstance3d extends SoundInstance { this.panner.maxDistance = value; } + /** + * Gets the maximum distance from the listener at which audio falloff stops. + * + * @type {number} + */ get maxDistance() { return this.panner.maxDistance; } /** - * The reference distance for reducing volume as the sound source moves further from the + * Sets the reference distance for reducing volume as the sound source moves further from the * listener. * * @type {number} @@ -147,12 +150,18 @@ class SoundInstance3d extends SoundInstance { this.panner.refDistance = value; } + /** + * Gets the reference distance for reducing volume as the sound source moves further from the + * listener. + * + * @type {number} + */ get refDistance() { return this.panner.refDistance; } /** - * The factor used in the falloff equation. + * Sets the factor used in the falloff equation. * * @type {number} */ @@ -160,12 +169,17 @@ class SoundInstance3d extends SoundInstance { this.panner.rolloffFactor = value; } + /** + * Gets the factor used in the falloff equation. + * + * @type {number} + */ get rollOffFactor() { return this.panner.rolloffFactor; } /** - * Determines which algorithm to use to reduce the volume of the audio as it moves away from + * Sets which algorithm to use to reduce the volume of the audio as it moves away from * the listener. Can be: * * - {@link DISTANCE_LINEAR} @@ -180,6 +194,12 @@ class SoundInstance3d extends SoundInstance { this.panner.distanceModel = value; } + /** + * Gets which algorithm to use to reduce the volume of the audio as it moves away from + * the listener. + * + * @type {string} + */ get distanceModel() { return this.panner.distanceModel; } diff --git a/src/platform/sound/manager.js b/src/platform/sound/manager.js index 0557c6bde75..1d81a45198f 100644 --- a/src/platform/sound/manager.js +++ b/src/platform/sound/manager.js @@ -58,8 +58,8 @@ class SoundManager extends EventHandler { } /** - * Global volume for the manager. All {@link SoundInstance}s will scale their volume with this - * volume. Valid between [0, 1]. + * Sets the global volume for the manager. All {@link SoundInstance}s will scale their volume + * with this volume. Valid between [0, 1]. * * @type {number} */ @@ -69,6 +69,11 @@ class SoundManager extends EventHandler { this.fire('volumechange', volume); } + /** + * Gets the global volume for the manager. + * + * @type {number} + */ get volume() { return this._volume; } diff --git a/src/scene/animation/skeleton.js b/src/scene/animation/skeleton.js index 8df0e8275aa..e2f7df06a1b 100644 --- a/src/scene/animation/skeleton.js +++ b/src/scene/animation/skeleton.js @@ -74,7 +74,7 @@ class Skeleton { } /** - * Animation currently assigned to skeleton. + * Sets the animation on the skeleton. * * @type {import('./animation.js').Animation} */ @@ -83,13 +83,18 @@ class Skeleton { this.currentTime = 0; } + /** + * Gets the animation on the skeleton. + * + * @type {import('./animation.js').Animation} + */ get animation() { return this._animation; } /** - * Current time of currently active animation in seconds. This value is between zero and the - * duration of the animation. + * Sets the current time of the currently active animation in seconds. This value is between + * zero and the duration of the animation. * * @type {number} */ @@ -106,12 +111,17 @@ class Skeleton { this.updateGraph(); } + /** + * Gets the current time of the currently active animation in seconds. + * + * @type {number} + */ get currentTime() { return this._time; } /** - * Read-only property that returns number of nodes of a skeleton. + * Gets the number of nodes in the skeleton. * * @type {number} */ diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index dff45784aa4..07a93201ba4 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -108,7 +108,7 @@ class GraphNode extends EventHandler { /** @private */ _labels = {}; - // Local-space properties of transform (only first 3 are settable by the user) + // Local space properties of transform (only first 3 are settable by the user) /** * @type {Vec3} * @private @@ -133,7 +133,7 @@ class GraphNode extends EventHandler { */ localEulerAngles = new Vec3(); // Only calculated on request - // World-space properties of transform + // World space properties of transform /** * @type {Vec3} * @private @@ -293,7 +293,7 @@ class GraphNode extends EventHandler { } /** - * The normalized local space X-axis vector of the graph node in world space. + * Gets the normalized local space X-axis vector of the graph node in world space. * * @type {Vec3} */ @@ -305,7 +305,7 @@ class GraphNode extends EventHandler { } /** - * The normalized local space Y-axis vector of the graph node in world space. + * Gets the normalized local space Y-axis vector of the graph node in world space. * * @type {Vec3} */ @@ -317,7 +317,7 @@ class GraphNode extends EventHandler { } /** - * The normalized local space negative Z-axis vector of the graph node in world space. + * Gets the normalized local space negative Z-axis vector of the graph node in world space. * * @type {Vec3} */ @@ -329,9 +329,9 @@ class GraphNode extends EventHandler { } /** - * A matrix used to transform the normal. + * Gets the 3x3 transformation matrix used to transform normals. * - * @type {Mat3} + * @type {Mat3} * @ignore */ get normalMatrix() { @@ -346,9 +346,9 @@ class GraphNode extends EventHandler { } /** - * Enable or disable a GraphNode. If one of the GraphNode's parents is disabled there will be - * no other side effects. If all the parents are enabled then the new value will activate or - * deactivate all the enabled children of the GraphNode. + * Sets the enabled state of the GraphNode. If one of the GraphNode's parents is disabled there + * will be no other side effects. If all the parents are enabled then the new value will + * activate or deactivate all the enabled children of the GraphNode. * * @type {boolean} */ @@ -364,6 +364,11 @@ class GraphNode extends EventHandler { } } + /** + * Gets the enabled state of the GraphNode. + * + * @type {boolean} + */ get enabled() { // make sure to check this._enabled too because if that // was false when a parent was updated the _enabledInHierarchy @@ -372,7 +377,7 @@ class GraphNode extends EventHandler { } /** - * A read-only property to get a parent graph node. + * Gets the parent of this graph node. * * @type {GraphNode|null} */ @@ -381,7 +386,7 @@ class GraphNode extends EventHandler { } /** - * A read-only property to get the path of the graph node relative to the root of the hierarchy. + * Gets the path of this graph node relative to the root of the hierarchy. * * @type {string} */ @@ -400,7 +405,7 @@ class GraphNode extends EventHandler { } /** - * A read-only property to get highest graph node from current node. + * Gets the oldest ancestor graph node from this graph node. * * @type {GraphNode} */ @@ -413,7 +418,7 @@ class GraphNode extends EventHandler { } /** - * A read-only property to get the children of this graph node. + * Gets the children of this graph node. * * @type {GraphNode[]} */ @@ -422,9 +427,9 @@ class GraphNode extends EventHandler { } /** - * A read-only property to get the depth of this child within the graph. Note that for - * performance reasons this is only recalculated when a node is added to a new parent, i.e. It - * is not recalculated when a node is simply removed from the graph. + * Gets the depth of this child within the graph. Note that for performance reasons this is + * only recalculated when a node is added to a new parent. In other words, it is not + * recalculated when a node is simply removed from the graph. * * @type {number} */ @@ -761,7 +766,7 @@ class GraphNode extends EventHandler { /** * Get the world space rotation for the specified GraphNode in Euler angle form. The rotation * is returned as euler angles in a {@link Vec3}. The value returned by this function should be - * considered read-only. In order to set the world-space rotation of the graph node, use + * considered read-only. In order to set the world space rotation of the graph node, use * {@link GraphNode#setEulerAngles}. * * @returns {Vec3} The world space rotation of the graph node in Euler angle form. @@ -853,7 +858,7 @@ class GraphNode extends EventHandler { /** * Get the world space position for the specified GraphNode. The position is returned as a * {@link Vec3}. The value returned by this function should be considered read-only. In order - * to set the world-space position of the graph node, use {@link GraphNode#setPosition}. + * to set the world space position of the graph node, use {@link GraphNode#setPosition}. * * @returns {Vec3} The world space position of the graph node. * @example @@ -869,7 +874,7 @@ class GraphNode extends EventHandler { /** * Get the world space rotation for the specified GraphNode. The rotation is returned as a * {@link Quat}. The value returned by this function should be considered read-only. In order - * to set the world-space rotation of the graph node, use {@link GraphNode#setRotation}. + * to set the world space rotation of the graph node, use {@link GraphNode#setRotation}. * * @returns {Quat} The world space rotation of the graph node as a quaternion. * @example @@ -920,7 +925,7 @@ class GraphNode extends EventHandler { } /** - * Returns cached value of negative scale of the world transform. + * Gets the cached value of negative scale sign of the world transform. * * @returns {number} -1 if world transform has negative scale, 1 otherwise. * @ignore @@ -959,15 +964,15 @@ class GraphNode extends EventHandler { } /** - * Sets the local-space rotation of the specified graph node using euler angles. Eulers are + * Sets the local space rotation of the specified graph node using euler angles. Eulers are * interpreted in XYZ order. Eulers must be specified in degrees. This function has two valid - * signatures: you can either pass a 3D vector or 3 numbers to specify the local-space euler + * signatures: you can either pass a 3D vector or 3 numbers to specify the local space euler * rotation. * - * @param {Vec3|number} x - 3-dimensional vector holding eulers or rotation around local-space + * @param {Vec3|number} x - 3-dimensional vector holding eulers or rotation around local space * x-axis in degrees. - * @param {number} [y] - Rotation around local-space y-axis in degrees. - * @param {number} [z] - Rotation around local-space z-axis in degrees. + * @param {number} [y] - Rotation around local space y-axis in degrees. + * @param {number} [z] - Rotation around local space z-axis in degrees. * @example * // Set rotation of 90 degrees around y-axis via 3 numbers * this.entity.setLocalEulerAngles(0, 90, 0); @@ -984,14 +989,14 @@ class GraphNode extends EventHandler { } /** - * Sets the local-space position of the specified graph node. This function has two valid - * signatures: you can either pass a 3D vector or 3 numbers to specify the local-space + * Sets the local space position of the specified graph node. This function has two valid + * signatures: you can either pass a 3D vector or 3 numbers to specify the local space * position. * - * @param {Vec3|number} x - 3-dimensional vector holding local-space position or - * x-coordinate of local-space position. - * @param {number} [y] - Y-coordinate of local-space position. - * @param {number} [z] - Z-coordinate of local-space position. + * @param {Vec3|number} x - 3-dimensional vector holding local space position or + * x-coordinate of local space position. + * @param {number} [y] - Y-coordinate of local space position. + * @param {number} [z] - Z-coordinate of local space position. * @example * // Set via 3 numbers * this.entity.setLocalPosition(0, 10, 0); @@ -1012,15 +1017,15 @@ class GraphNode extends EventHandler { } /** - * Sets the local-space rotation of the specified graph node. This function has two valid - * signatures: you can either pass a quaternion or 3 numbers to specify the local-space + * Sets the local space rotation of the specified graph node. This function has two valid + * signatures: you can either pass a quaternion or 3 numbers to specify the local space * rotation. * - * @param {Quat|number} x - Quaternion holding local-space rotation or x-component of - * local-space quaternion rotation. - * @param {number} [y] - Y-component of local-space quaternion rotation. - * @param {number} [z] - Z-component of local-space quaternion rotation. - * @param {number} [w] - W-component of local-space quaternion rotation. + * @param {Quat|number} x - Quaternion holding local space rotation or x-component of + * local space quaternion rotation. + * @param {number} [y] - Y-component of local space quaternion rotation. + * @param {number} [z] - Z-component of local space quaternion rotation. + * @param {number} [w] - W-component of local space quaternion rotation. * @example * // Set via 4 numbers * this.entity.setLocalRotation(0, 0, 0, 1); @@ -1041,13 +1046,13 @@ class GraphNode extends EventHandler { } /** - * Sets the local-space scale factor of the specified graph node. This function has two valid - * signatures: you can either pass a 3D vector or 3 numbers to specify the local-space scale. + * Sets the local space scale factor of the specified graph node. This function has two valid + * signatures: you can either pass a 3D vector or 3 numbers to specify the local space scale. * - * @param {Vec3|number} x - 3-dimensional vector holding local-space scale or x-coordinate - * of local-space scale. - * @param {number} [y] - Y-coordinate of local-space scale. - * @param {number} [z] - Z-coordinate of local-space scale. + * @param {Vec3|number} x - 3-dimensional vector holding local space scale or x-coordinate + * of local space scale. + * @param {number} [y] - Y-coordinate of local space scale. + * @param {number} [z] - Z-coordinate of local space scale. * @example * // Set via 3 numbers * this.entity.setLocalScale(10, 10, 10); @@ -1108,14 +1113,14 @@ class GraphNode extends EventHandler { } /** - * Sets the world-space position of the specified graph node. This function has two valid - * signatures: you can either pass a 3D vector or 3 numbers to specify the world-space + * Sets the world space position of the specified graph node. This function has two valid + * signatures: you can either pass a 3D vector or 3 numbers to specify the world space * position. * - * @param {Vec3|number} x - 3-dimensional vector holding world-space position or - * x-coordinate of world-space position. - * @param {number} [y] - Y-coordinate of world-space position. - * @param {number} [z] - Z-coordinate of world-space position. + * @param {Vec3|number} x - 3-dimensional vector holding world space position or + * x-coordinate of world space position. + * @param {number} [y] - Y-coordinate of world space position. + * @param {number} [z] - Z-coordinate of world space position. * @example * // Set via 3 numbers * this.entity.setPosition(0, 10, 0); @@ -1143,15 +1148,15 @@ class GraphNode extends EventHandler { } /** - * Sets the world-space rotation of the specified graph node. This function has two valid - * signatures: you can either pass a quaternion or 3 numbers to specify the world-space + * Sets the world space rotation of the specified graph node. This function has two valid + * signatures: you can either pass a quaternion or 3 numbers to specify the world space * rotation. * - * @param {Quat|number} x - Quaternion holding world-space rotation or x-component of - * world-space quaternion rotation. - * @param {number} [y] - Y-component of world-space quaternion rotation. - * @param {number} [z] - Z-component of world-space quaternion rotation. - * @param {number} [w] - W-component of world-space quaternion rotation. + * @param {Quat|number} x - Quaternion holding world space rotation or x-component of + * world space quaternion rotation. + * @param {number} [y] - Y-component of world space quaternion rotation. + * @param {number} [z] - Z-component of world space quaternion rotation. + * @param {number} [w] - W-component of world space quaternion rotation. * @example * // Set via 4 numbers * this.entity.setRotation(0, 0, 0, 1); @@ -1180,20 +1185,20 @@ class GraphNode extends EventHandler { } /** - * Sets the world-space rotation of the specified graph node using euler angles. Eulers are + * Sets the world space rotation of the specified graph node using euler angles. Eulers are * interpreted in XYZ order. Eulers must be specified in degrees. This function has two valid - * signatures: you can either pass a 3D vector or 3 numbers to specify the world-space euler + * signatures: you can either pass a 3D vector or 3 numbers to specify the world space euler * rotation. * - * @param {Vec3|number} x - 3-dimensional vector holding eulers or rotation around world-space + * @param {Vec3|number} x - 3-dimensional vector holding eulers or rotation around world space * x-axis in degrees. - * @param {number} [y] - Rotation around world-space y-axis in degrees. - * @param {number} [z] - Rotation around world-space z-axis in degrees. + * @param {number} [y] - Rotation around world space y-axis in degrees. + * @param {number} [z] - Rotation around world space z-axis in degrees. * @example - * // Set rotation of 90 degrees around world-space y-axis via 3 numbers + * // Set rotation of 90 degrees around world space y-axis via 3 numbers * this.entity.setEulerAngles(0, 90, 0); * @example - * // Set rotation of 90 degrees around world-space y-axis via a vector + * // Set rotation of 90 degrees around world space y-axis via a vector * const angles = new pc.Vec3(0, 90, 0); * this.entity.setEulerAngles(angles); */ @@ -1470,11 +1475,11 @@ class GraphNode extends EventHandler { * function has two valid signatures. Either pass 3D vectors for the look at coordinate and up * vector, or pass numbers to represent the vectors. * - * @param {Vec3|number} x - If passing a 3D vector, this is the world-space coordinate to look at. - * Otherwise, it is the x-component of the world-space coordinate to look at. - * @param {Vec3|number} [y] - If passing a 3D vector, this is the world-space up vector for look at - * transform. Otherwise, it is the y-component of the world-space coordinate to look at. - * @param {number} [z] - Z-component of the world-space coordinate to look at. + * @param {Vec3|number} x - If passing a 3D vector, this is the world space coordinate to look at. + * Otherwise, it is the x-component of the world space coordinate to look at. + * @param {Vec3|number} [y] - If passing a 3D vector, this is the world space up vector for look at + * transform. Otherwise, it is the y-component of the world space coordinate to look at. + * @param {number} [z] - Z-component of the world space coordinate to look at. * @param {number} [ux] - X-component of the up vector for the look at transform. Defaults to 0. * @param {number} [uy] - Y-component of the up vector for the look at transform. Defaults to 1. * @param {number} [uz] - Z-component of the up vector for the look at transform. Defaults to 0. @@ -1490,7 +1495,7 @@ class GraphNode extends EventHandler { * // Look at the world space origin, using the (default) positive y-axis for up * this.entity.lookAt(0, 0, 0); * @example - * // Look at world-space coordinate [10, 10, 10], using the negative world y-axis for up + * // Look at world space coordinate [10, 10, 10], using the negative world y-axis for up * this.entity.lookAt(10, 10, 10, 0, -1, 0); */ lookAt(x, y, z, ux = 0, uy = 1, uz = 0) { @@ -1515,14 +1520,14 @@ class GraphNode extends EventHandler { } /** - * Translates the graph node in world-space by the specified translation vector. This function + * Translates the graph node in world space by the specified translation vector. This function * has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the - * world-space translation. + * world space translation. * - * @param {Vec3|number} x - 3-dimensional vector holding world-space translation or - * x-coordinate of world-space translation. - * @param {number} [y] - Y-coordinate of world-space translation. - * @param {number} [z] - Z-coordinate of world-space translation. + * @param {Vec3|number} x - 3-dimensional vector holding world space translation or + * x-coordinate of world space translation. + * @param {number} [y] - Y-coordinate of world space translation. + * @param {number} [z] - Z-coordinate of world space translation. * @example * // Translate via 3 numbers * this.entity.translate(10, 0, 0); @@ -1543,14 +1548,14 @@ class GraphNode extends EventHandler { } /** - * Translates the graph node in local-space by the specified translation vector. This function + * Translates the graph node in local space by the specified translation vector. This function * has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the - * local-space translation. + * local space translation. * - * @param {Vec3|number} x - 3-dimensional vector holding local-space translation or - * x-coordinate of local-space translation. - * @param {number} [y] - Y-coordinate of local-space translation. - * @param {number} [z] - Z-coordinate of local-space translation. + * @param {Vec3|number} x - 3-dimensional vector holding local space translation or + * x-coordinate of local space translation. + * @param {number} [y] - Y-coordinate of local space translation. + * @param {number} [z] - Z-coordinate of local space translation. * @example * // Translate via 3 numbers * this.entity.translateLocal(10, 0, 0); @@ -1574,14 +1579,14 @@ class GraphNode extends EventHandler { } /** - * Rotates the graph node in world-space by the specified Euler angles. Eulers are specified in + * Rotates the graph node in world space by the specified Euler angles. Eulers are specified in * degrees in XYZ order. This function has two valid signatures: you can either pass a 3D - * vector or 3 numbers to specify the world-space rotation. + * vector or 3 numbers to specify the world space rotation. * - * @param {Vec3|number} x - 3-dimensional vector holding world-space rotation or - * rotation around world-space x-axis in degrees. - * @param {number} [y] - Rotation around world-space y-axis in degrees. - * @param {number} [z] - Rotation around world-space z-axis in degrees. + * @param {Vec3|number} x - 3-dimensional vector holding world space rotation or + * rotation around world space x-axis in degrees. + * @param {number} [y] - Rotation around world space y-axis in degrees. + * @param {number} [z] - Rotation around world space z-axis in degrees. * @example * // Rotate via 3 numbers * this.entity.rotate(0, 90, 0); @@ -1609,14 +1614,14 @@ class GraphNode extends EventHandler { } /** - * Rotates the graph node in local-space by the specified Euler angles. Eulers are specified in + * Rotates the graph node in local space by the specified Euler angles. Eulers are specified in * degrees in XYZ order. This function has two valid signatures: you can either pass a 3D - * vector or 3 numbers to specify the local-space rotation. + * vector or 3 numbers to specify the local space rotation. * - * @param {Vec3|number} x - 3-dimensional vector holding local-space rotation or - * rotation around local-space x-axis in degrees. - * @param {number} [y] - Rotation around local-space y-axis in degrees. - * @param {number} [z] - Rotation around local-space z-axis in degrees. + * @param {Vec3|number} x - 3-dimensional vector holding local space rotation or + * rotation around local space x-axis in degrees. + * @param {number} [y] - Rotation around local space y-axis in degrees. + * @param {number} [z] - Rotation around local space z-axis in degrees. * @example * // Rotate via 3 numbers * this.entity.rotateLocal(0, 90, 0); diff --git a/src/scene/layer.js b/src/scene/layer.js index cc7683ef1ef..b9931213f4e 100644 --- a/src/scene/layer.js +++ b/src/scene/layer.js @@ -444,7 +444,7 @@ class Layer { } /** - * Enable the layer. Disabled layers are skipped. Defaults to true. + * Sets the enabled state of the layer. Disabled layers are skipped. Defaults to true. * * @type {boolean} */ @@ -462,12 +462,17 @@ class Layer { } } + /** + * Gets the enabled state of the layer. + * + * @type {boolean} + */ get enabled() { return this._enabled; } /** - * If true, the camera will clear the color buffer when it renders this layer. + * Sets whether the camera will clear the color buffer when it renders this layer. * * @type {boolean} */ @@ -476,12 +481,17 @@ class Layer { this._dirtyComposition = true; } + /** + * Gets whether the camera will clear the color buffer when it renders this layer. + * + * @type {boolean} + */ get clearColorBuffer() { return this._clearColorBuffer; } /** - * If true, the camera will clear the depth buffer when it renders this layer. + * Sets whether the camera will clear the depth buffer when it renders this layer. * * @type {boolean} */ @@ -490,12 +500,17 @@ class Layer { this._dirtyComposition = true; } + /** + * Gets whether the camera will clear the depth buffer when it renders this layer. + * + * @type {boolean} + */ get clearDepthBuffer() { return this._clearDepthBuffer; } /** - * If true, the camera will clear the stencil buffer when it renders this layer. + * Sets whether the camera will clear the stencil buffer when it renders this layer. * * @type {boolean} */ @@ -504,12 +519,17 @@ class Layer { this._dirtyComposition = true; } + /** + * Gets whether the camera will clear the stencil buffer when it renders this layer. + * + * @type {boolean} + */ get clearStencilBuffer() { return this._clearStencilBuffer; } /** - * True if the layer contains omni or spot lights + * Gets whether the layer contains omni or spot lights. * * @type {boolean} * @ignore @@ -519,7 +539,7 @@ class Layer { } /** - * Returns lights used by clustered lighting in a set. + * Gets the lights used by clustered lighting in a set. * * @type {Set} * @ignore diff --git a/src/scene/lighting/lighting-params.js b/src/scene/lighting/lighting-params.js index d294b6c4e8a..04d292c57d7 100644 --- a/src/scene/lighting/lighting-params.js +++ b/src/scene/lighting/lighting-params.js @@ -75,8 +75,8 @@ class LightingParams { } /** - * Number of cells along each world-space axis the space containing lights - * is subdivided into. Defaults to Vec(10, 3, 10). + * Sets the number of cells along each world space axis the space containing lights is + * subdivided into. Defaults to `[10, 3, 10]`. * * @type {Vec3} */ @@ -84,12 +84,18 @@ class LightingParams { this._cells.copy(value); } + /** + * Gets the number of cells along each world space axis the space containing lights is + * subdivided into. + * + * @type {Vec3} + */ get cells() { return this._cells; } /** - * Maximum number of lights a cell can store. Defaults to 255. + * Sets the maximum number of lights a cell can store. Defaults to 255. * * @type {number} */ @@ -97,12 +103,17 @@ class LightingParams { this._maxLightsPerCell = math.clamp(value, 1, 255); } + /** + * Gets the maximum number of lights a cell can store. + * + * @type {number} + */ get maxLightsPerCell() { return this._maxLightsPerCell; } /** - * Resolution of the atlas texture storing all non-directional cookie textures. + * Sets the resolution of the atlas texture storing all non-directional cookie textures. * Defaults to 2048. * * @type {number} @@ -111,12 +122,17 @@ class LightingParams { this._cookieAtlasResolution = math.clamp(value, 32, this._maxTextureSize); } + /** + * Gets the resolution of the atlas texture storing all non-directional cookie textures. + * + * @type {number} + */ get cookieAtlasResolution() { return this._cookieAtlasResolution; } /** - * Resolution of the atlas texture storing all non-directional shadow textures. + * Sets the resolution of the atlas texture storing all non-directional shadow textures. * Defaults to 2048. * * @type {number} @@ -125,12 +141,17 @@ class LightingParams { this._shadowAtlasResolution = math.clamp(value, 32, this._maxTextureSize); } + /** + * Gets the resolution of the atlas texture storing all non-directional shadow textures. + * + * @type {number} + */ get shadowAtlasResolution() { return this._shadowAtlasResolution; } /** - * The type of shadow filtering used by all shadows. Can be: + * Sets the type of shadow filtering used by all shadows. Can be: * * - {@link SHADOW_PCF1}: PCF 1x1 sampling. * - {@link SHADOW_PCF3}: PCF 3x3 sampling. @@ -149,13 +170,17 @@ class LightingParams { } } + /** + * Gets the type of shadow filtering used by all shadows. + * + * @type {number} + */ get shadowType() { return this._shadowType; } /** - * If set to true, the clustered lighting will support cookie textures. - * Defaults to false. + * Sets whether clustered lighting supports cookie textures. Defaults to false. * * @type {boolean} */ @@ -168,13 +193,17 @@ class LightingParams { } } + /** + * Gets whether clustered lighting supports cookie textures. + * + * @type {boolean} + */ get cookiesEnabled() { return this._cookiesEnabled; } /** - * If set to true, the clustered lighting will support area lights. - * Defaults to false. + * Sets whether clustered lighting supports area lights. Defaults to false. * * @type {boolean} */ @@ -191,13 +220,17 @@ class LightingParams { } } + /** + * Gets whether clustered lighting supports area lights. + * + * @type {boolean} + */ get areaLightsEnabled() { return this._areaLightsEnabled; } /** - * If set to true, the clustered lighting will support shadows. - * Defaults to true. + * Sets whether clustered lighting supports shadow casting. Defaults to true. * * @type {boolean} */ @@ -210,6 +243,11 @@ class LightingParams { } } + /** + * Gets whether clustered lighting supports shadow casting. + * + * @type {boolean} + */ get shadowsEnabled() { return this._shadowsEnabled; } diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index 4232343fa71..9f38fc701b0 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -149,8 +149,9 @@ class Material { stencilBack = null; /** - * Offsets the output depth buffer value. Useful for decals to prevent z-fighting. Typically - * a small negative value (-0.1) is used to render the mesh slightly closer to the camera. + * Sets the offset for the output depth buffer value. Useful for decals to prevent z-fighting. + * Typically a small negative value (-0.1) is used to render the mesh slightly closer to the + * camera. * * @type {number} */ @@ -158,13 +159,18 @@ class Material { this._depthState.depthBias = value; } + /** + * Gets the offset for the output depth buffer value. + * + * @type {number} + */ get depthBias() { return this._depthState.depthBias; } /** - * Same as {@link Material#depthBias}, but also depends on the slope of the triangle relative - * to the camera. + * Sets the offset for the output depth buffer value based on the slope of the triangle + * relative to the camera. * * @type {number} */ @@ -172,6 +178,12 @@ class Material { this._depthState.depthBiasSlope = value; } + /** + * Gets the offset for the output depth buffer value based on the slope of the triangle + * relative to the camera. + * + * @type {number} + */ get slopeDepthBias() { return this._depthState.depthBiasSlope; } @@ -183,9 +195,10 @@ class Material { dirty = true; /** - * If true, the red component of fragments generated by the shader of this material is written - * to the color buffer of the currently active render target. If false, the red component will - * not be written. Defaults to true. + * Sets whether the red channel is written to the color buffer. If true, the red component of + * fragments generated by the shader of this material is written to the color buffer of the + * currently active render target. If false, the red component will not be written. Defaults to + * true. * * @type {boolean} */ @@ -193,14 +206,20 @@ class Material { this._blendState.redWrite = value; } + /** + * Gets whether the red channel is written to the color buffer. + * + * @type {boolean} + */ get redWrite() { return this._blendState.redWrite; } /** - * If true, the green component of fragments generated by the shader of this material is - * written to the color buffer of the currently active render target. If false, the green - * component will not be written. Defaults to true. + * Sets whether the green channel is written to the color buffer. If true, the red component of + * fragments generated by the shader of this material is written to the color buffer of the + * currently active render target. If false, the green component will not be written. Defaults + * to true. * * @type {boolean} */ @@ -208,14 +227,20 @@ class Material { this._blendState.greenWrite = value; } + /** + * Gets whether the green channel is written to the color buffer. + * + * @type {boolean} + */ get greenWrite() { return this._blendState.greenWrite; } /** - * If true, the blue component of fragments generated by the shader of this material is - * written to the color buffer of the currently active render target. If false, the blue - * component will not be written. Defaults to true. + * Sets whether the blue channel is written to the color buffer. If true, the red component of + * fragments generated by the shader of this material is written to the color buffer of the + * currently active render target. If false, the blue component will not be written. Defaults + * to true. * * @type {boolean} */ @@ -223,14 +248,20 @@ class Material { this._blendState.blueWrite = value; } + /** + * Gets whether the blue channel is written to the color buffer. + * + * @type {boolean} + */ get blueWrite() { return this._blendState.blueWrite; } /** - * If true, the alpha component of fragments generated by the shader of this material is - * written to the color buffer of the currently active render target. If false, the alpha - * component will not be written. Defaults to true. + * Sets whether the alpha channel is written to the color buffer. If true, the red component of + * fragments generated by the shader of this material is written to the color buffer of the + * currently active render target. If false, the alpha component will not be written. Defaults + * to true. * * @type {boolean} */ @@ -238,12 +269,17 @@ class Material { this._blendState.alphaWrite = value; } + /** + * Gets whether the alpha channel is written to the color buffer. + * + * @type {boolean} + */ get alphaWrite() { return this._blendState.alphaWrite; } /** - * The shader used by this material to render mesh instances (default is null). + * Sets the shader used by this material to render mesh instances. Defaults to `null`. * * @type {import('../../platform/graphics/shader.js').Shader|null} */ @@ -251,6 +287,11 @@ class Material { this._shader = shader; } + /** + * Gets the shader used by this material to render mesh instances. + * + * @type {import('../../platform/graphics/shader.js').Shader|null} + */ get shader() { return this._shader; } @@ -269,24 +310,29 @@ class Material { } /** - * Controls how fragment shader outputs are blended when being written to the currently active - * render target. This overwrites blending type set using {@link Material#blendType}, and - * offers more control over blending. + * Sets the blend state for this material. Controls how fragment shader outputs are blended + * when being written to the currently active render target. This overwrites blending type set + * using {@link Material#blendType}, and offers more control over blending. * - * @type { BlendState } + * @type {BlendState} */ set blendState(value) { this._blendState.copy(value); this._updateTransparency(); } + /** + * Gets the blend state for this material. + * + * @type {BlendState} + */ get blendState() { return this._blendState; } /** - * Controls how fragment shader outputs are blended when being written to the currently active - * render target. Can be: + * Sets the blend mode for this material. Controls how fragment shader outputs are blended when + * being written to the currently active render target. Can be: * * - {@link BLEND_SUBTRACTIVE}: Subtract the color of the source fragment from the destination * fragment and write the result to the frame buffer. @@ -326,6 +372,11 @@ class Material { this._updateMeshInstanceKeys(); } + /** + * Gets the blend mode for this material. + * + * @type {number} + */ get blendType() { if (!this.transparent) { return BLEND_NONE; @@ -348,21 +399,26 @@ class Material { * Sets the depth state. Note that this can also be done by using {@link Material#depthTest}, * {@link Material#depthFunc} and {@link Material#depthWrite}. * - * @type { DepthState } + * @type {DepthState} */ set depthState(value) { this._depthState.copy(value); } + /** + * Gets the depth state. + * + * @type {DepthState} + */ get depthState() { return this._depthState; } /** - * If true, fragments generated by the shader of this material are only written to the current - * render target if they pass the depth test. If false, fragments generated by the shader of - * this material are written to the current render target regardless of what is in the depth - * buffer. Defaults to true. + * Sets whether depth testing is enabled. If true, fragments generated by the shader of this + * material are only written to the current render target if they pass the depth test. If + * false, fragments generated by the shader of this material are written to the current render + * target regardless of what is in the depth buffer. Defaults to true. * * @type {boolean} */ @@ -370,13 +426,18 @@ class Material { this._depthState.test = value; } + /** + * Gets whether depth testing is enabled. + * + * @type {boolean} + */ get depthTest() { return this._depthState.test; } /** - * Controls how the depth of new fragments is compared against the current depth contained in - * the depth buffer. Can be: + * Sets the depth test function. Controls how the depth of new fragments is compared against + * the current depth contained in the depth buffer. Can be: * * - {@link FUNC_NEVER}: don't draw * - {@link FUNC_LESS}: draw if new depth < depth buffer @@ -395,14 +456,19 @@ class Material { this._depthState.func = value; } + /** + * Gets the depth test function. + * + * @type {number} + */ get depthFunc() { return this._depthState.func; } /** - * If true, fragments generated by the shader of this material write a depth value to the depth - * buffer of the currently active render target. If false, no depth value is written. Defaults - * to true. + * Sets whether depth writing is enabled. If true, fragments generated by the shader of this + * material write a depth value to the depth buffer of the currently active render target. If + * false, no depth value is written. Defaults to true. * * @type {boolean} */ @@ -410,6 +476,11 @@ class Material { this._depthState.write = value; } + /** + * Gets whether depth writing is enabled. + * + * @type {boolean} + */ get depthWrite() { return this._depthState.write; } diff --git a/src/scene/mesh-instance.js b/src/scene/mesh-instance.js index e863201f255..9f60fd6fe65 100644 --- a/src/scene/mesh-instance.js +++ b/src/scene/mesh-instance.js @@ -333,7 +333,7 @@ class MeshInstance { } /** - * The render style of the mesh instance. Can be: + * Sets the render style of the mesh instance. Can be: * * - {@link RENDERSTYLE_SOLID} * - {@link RENDERSTYLE_WIREFRAME} @@ -348,12 +348,17 @@ class MeshInstance { this.mesh.prepareRenderState(renderStyle); } + /** + * Gets the render style of the mesh instance. + * + * @type {number} + */ get renderStyle() { return this._renderStyle; } /** - * The graphics mesh being instanced. + * Sets the graphics mesh being instanced. * * @type {import('./mesh.js').Mesh} */ @@ -373,12 +378,17 @@ class MeshInstance { } } + /** + * Gets the graphics mesh being instanced. + * + * @type {import('./mesh.js').Mesh} + */ get mesh() { return this._mesh; } /** - * The world space axis-aligned bounding box for this mesh instance. + * Sets the world space axis-aligned bounding box for this mesh instance. * * @type {BoundingBox} */ @@ -386,6 +396,11 @@ class MeshInstance { this._aabb = aabb; } + /** + * Gets the world space axis-aligned bounding box for this mesh instance. + * + * @type {BoundingBox} + */ get aabb() { // use specified world space aabb if (!this._updateAabb) { @@ -542,7 +557,7 @@ class MeshInstance { } /** - * The material used by this mesh instance. + * Sets the material used by this mesh instance. * * @type {import('./materials/material.js').Material} */ @@ -571,6 +586,11 @@ class MeshInstance { } } + /** + * Gets the material used by this mesh instance. + * + * @type {import('./materials/material.js').Material} + */ get material() { return this._material; } @@ -592,18 +612,24 @@ class MeshInstance { } /** - * In some circumstances mesh instances are sorted by a distance calculation to determine their - * rendering order. Set this callback to override the default distance calculation, which gives - * the dot product of the camera forward vector and the vector between the camera position and - * the center of the mesh instance's axis-aligned bounding box. This option can be particularly - * useful for rendering transparent meshes in a better order than default. + * Sets the callback to calculate sort distance. In some circumstances mesh instances are + * sorted by a distance calculation to determine their rendering order. Set this callback to + * override the default distance calculation, which gives the dot product of the camera forward + * vector and the vector between the camera position and the center of the mesh instance's + * axis-aligned bounding box. This option can be particularly useful for rendering transparent + * meshes in a better order than the default. * - * @type {CalculateSortDistanceCallback} + * @type {CalculateSortDistanceCallback|null} */ set calculateSortDistance(calculateSortDistance) { this._calculateSortDistance = calculateSortDistance; } + /** + * Gets the callback to calculate sort distance. + * + * @type {CalculateSortDistanceCallback|null} + */ get calculateSortDistance() { return this._calculateSortDistance; } @@ -620,9 +646,10 @@ class MeshInstance { } /** - * The skin instance managing skinning of this mesh instance, or null if skinning is not used. + * Sets the skin instance managing skinning of this mesh instance. Set to null if skinning is + * not used. * - * @type {import('./skin-instance.js').SkinInstance} + * @type {import('./skin-instance.js').SkinInstance|null} */ set skinInstance(val) { this._skinInstance = val; @@ -630,14 +657,20 @@ class MeshInstance { this._setupSkinUpdate(); } + /** + * Gets the skin instance managing skinning of this mesh instance. + * + * @type {import('./skin-instance.js').SkinInstance|null} + */ get skinInstance() { return this._skinInstance; } /** - * The morph instance managing morphing of this mesh instance, or null if morphing is not used. + * Sets the morph instance managing morphing of this mesh instance. Set to null if morphing is + * not used. * - * @type {import('./morph-instance.js').MorphInstance} + * @type {import('./morph-instance.js').MorphInstance|null} */ set morphInstance(val) { @@ -654,6 +687,11 @@ class MeshInstance { this._updateShaderDefs(shaderDefs); } + /** + * Gets the morph instance managing morphing of this mesh instance. + * + * @type {import('./morph-instance.js').MorphInstance|null} + */ get morphInstance() { return this._morphInstance; } @@ -678,7 +716,7 @@ class MeshInstance { } /** - * Mask controlling which {@link LightComponent}s light this mesh instance, which + * Sets the mask controlling which {@link LightComponent}s light this mesh instance, which * {@link CameraComponent} sees it and in which {@link Layer} it is rendered. Defaults to 1. * * @type {number} @@ -688,12 +726,18 @@ class MeshInstance { this._updateShaderDefs(toggles | (val << 16)); } + /** + * Gets the mask controlling which {@link LightComponent}s light this mesh instance, which + * {@link CameraComponent} sees it and in which {@link Layer} it is rendered. + * + * @type {number} + */ get mask() { return this._shaderDefs >> 16; } /** - * Number of instances when using hardware instancing to render the mesh. + * Sets the number of instances when using hardware instancing to render the mesh. * * @type {number} */ @@ -702,6 +746,11 @@ class MeshInstance { this.instancingData.count = value; } + /** + * Gets the number of instances when using hardware instancing to render the mesh. + * + * @type {number} + */ get instancingCount() { return this.instancingData ? this.instancingData.count : 0; } diff --git a/src/scene/mesh.js b/src/scene/mesh.js index c7b99a87e88..2726041372b 100644 --- a/src/scene/mesh.js +++ b/src/scene/mesh.js @@ -333,7 +333,8 @@ class Mesh extends RefCountedObject { } /** - * The morph data (if any) that drives morph target animations for this mesh. + * Sets the morph data that drives morph target animations for this mesh. Set to null if + * morphing is not used. * * @type {import('./morph.js').Morph|null} */ @@ -352,12 +353,17 @@ class Mesh extends RefCountedObject { } } + /** + * Gets the morph data that drives morph target animations for this mesh. + * + * @type {import('./morph.js').Morph|null} + */ get morph() { return this._morph; } /** - * The axis-aligned bounding box for the object space vertices of this mesh. + * Sets the axis-aligned bounding box for the object space vertices of this mesh. * * @type {BoundingBox} */ @@ -366,6 +372,11 @@ class Mesh extends RefCountedObject { this._aabbVer++; } + /** + * Gets the axis-aligned bounding box for the object space vertices of this mesh. + * + * @type {BoundingBox} + */ get aabb() { return this._aabb; } diff --git a/src/scene/morph-target.js b/src/scene/morph-target.js index c3bb1d91988..aa8189345fc 100644 --- a/src/scene/morph-target.js +++ b/src/scene/morph-target.js @@ -73,7 +73,7 @@ class MorphTarget { } /** - * The name of the morph target. + * Gets the name of the morph target. * * @type {string} */ @@ -82,7 +82,7 @@ class MorphTarget { } /** - * The default weight of the morph target. + * Gets the default weight of the morph target. * * @type {number} */ diff --git a/src/scene/morph.js b/src/scene/morph.js index c25187de3a2..2660751d32a 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -286,7 +286,7 @@ class Morph extends RefCountedObject { } /** - * The array of morph targets. + * Gets the array of morph targets. * * @type {import('./morph-target.js').MorphTarget[]} */ diff --git a/src/scene/scene.js b/src/scene/scene.js index af6393e364d..464542ecd14 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -300,18 +300,19 @@ class Scene extends EventHandler { } /** - * Returns the default layer used by the immediate drawing functions. + * Gets the default layer used by the immediate drawing functions. * * @type {import('./layer.js').Layer} - * @private + * @ignore */ get defaultDrawLayer() { return this.layers.getLayerById(LAYERID_IMMEDIATE); } /** - * If {@link Scene#ambientBake} is true, this specifies the number of samples used to bake the - * ambient light into the lightmap. Defaults to 1. Maximum value is 255. + * Sets the number of samples used to bake the ambient light into the lightmap. Note that + * {@link Scene#ambientBake} must be true for this to have an effect. Defaults to 1. Maximum + * value is 255. * * @type {number} */ @@ -319,16 +320,21 @@ class Scene extends EventHandler { this._ambientBakeNumSamples = math.clamp(Math.floor(value), 1, 255); } + /** + * Gets the number of samples used to bake the ambient light into the lightmap. + * + * @type {number} + */ get ambientBakeNumSamples() { return this._ambientBakeNumSamples; } /** - * If {@link Scene#ambientBake} is true, this specifies a part of the sphere which represents - * the source of ambient light. The valid range is 0..1, representing a part of the sphere from - * top to the bottom. A value of 0.5 represents the upper hemisphere. A value of 1 represents a - * full sphere. Defaults to 0.4, which is a smaller upper hemisphere as this requires fewer - * samples to bake. + * Sets the part of the sphere which represents the source of ambient light. Note that + * {@link Scene#ambientBake} must be true for this to have an effect. The valid range is 0..1, + * representing a part of the sphere from top to the bottom. A value of 0.5 represents the + * upper hemisphere. A value of 1 represents a full sphere. Defaults to 0.4, which is a smaller + * upper hemisphere as this requires fewer samples to bake. * * @type {number} */ @@ -336,12 +342,17 @@ class Scene extends EventHandler { this._ambientBakeSpherePart = math.clamp(value, 0.001, 1); } + /** + * Gets the part of the sphere which represents the source of ambient light. + * + * @type {number} + */ get ambientBakeSpherePart() { return this._ambientBakeSpherePart; } /** - * True if the clustered lighting is enabled. Set to false before the first frame is rendered + * Sets whether clustered lighting is enabled. Set to false before the first frame is rendered * to use non-clustered lighting. Defaults to true. * * @type {boolean} @@ -361,12 +372,17 @@ class Scene extends EventHandler { this._clusteredLightingEnabled = value; } + /** + * Gets whether clustered lighting is enabled. + * + * @type {boolean} + */ get clusteredLightingEnabled() { return this._clusteredLightingEnabled; } /** - * The environment lighting atlas. + * Sets the environment lighting atlas. * * @type {import('../platform/graphics/texture.js').Texture} */ @@ -393,12 +409,17 @@ class Scene extends EventHandler { } } + /** + * Gets the environment lighting atlas. + * + * @type {import('../platform/graphics/texture.js').Texture} + */ get envAtlas() { return this._envAtlas; } /** - * The type of fog used by the scene. Can be: + * Sets the type of fog used by the scene. Can be: * * - {@link FOG_NONE} * - {@link FOG_LINEAR} @@ -416,12 +437,17 @@ class Scene extends EventHandler { } } + /** + * Gets the type of fog used by the scene. + * + * @type {string} + */ get fog() { return this._fog; } /** - * The gamma correction to apply when rendering the scene. Can be: + * Sets the gamma correction to apply when rendering the scene. Can be: * * - {@link GAMMA_NONE} * - {@link GAMMA_SRGB} @@ -437,12 +463,17 @@ class Scene extends EventHandler { } } + /** + * Gets the gamma correction to apply when rendering the scene. + * + * @type {number} + */ get gammaCorrection() { return this._gammaCorrection; } /** - * A {@link LayerComposition} that defines rendering order of this scene. + * Sets the {@link LayerComposition} that defines rendering order of this scene. * * @type {import('./composition/layer-composition.js').LayerComposition} */ @@ -452,6 +483,11 @@ class Scene extends EventHandler { this.fire('set:layers', prev, layers); } + /** + * Gets the {@link LayerComposition} that defines rendering order of this scene. + * + * @type {import('./composition/layer-composition.js').LayerComposition} + */ get layers() { return this._layers; } @@ -461,7 +497,7 @@ class Scene extends EventHandler { } /** - * A {@link LightingParams} that defines lighting parameters. + * Gets the {@link LightingParams} that define lighting parameters. * * @type {LightingParams} */ @@ -470,7 +506,7 @@ class Scene extends EventHandler { } /** - * A range parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled} + * Sets the range parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled} * is enabled. Larger value applies more widespread blur. This needs to be a positive non-zero * value. Defaults to 10. * @@ -480,12 +516,17 @@ class Scene extends EventHandler { this._lightmapFilterRange = Math.max(value, 0.001); } + /** + * Gets the range parameter of the bilateral filter. + * + * @type {number} + */ get lightmapFilterRange() { return this._lightmapFilterRange; } /** - * A spatial parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled} + * Sets the spatial parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled} * is enabled. Larger value blurs less similar colors. This needs to be a positive non-zero * value. Defaults to 0.2. * @@ -495,12 +536,17 @@ class Scene extends EventHandler { this._lightmapFilterSmoothness = Math.max(value, 0.001); } + /** + * Gets the spatial parameter of the bilateral filter. + * + * @type {number} + */ get lightmapFilterSmoothness() { return this._lightmapFilterSmoothness; } /** - * Set of 6 prefiltered cubemaps. + * Sets the 6 prefiltered cubemaps acting as the source of image-based lighting. * * @type {import('../platform/graphics/texture.js').Texture[]} */ @@ -532,12 +578,17 @@ class Scene extends EventHandler { } } + /** + * Gets the 6 prefiltered cubemaps acting as the source of image-based lighting. + * + * @type {import('../platform/graphics/texture.js').Texture[]} + */ get prefilteredCubemaps() { return this._prefilteredCubemaps; } /** - * The base cubemap texture used as the scene's skybox, if mip level is 0. Defaults to null. + * Sets the base cubemap texture used as the scene's skybox when skyboxMip is 0. Defaults to null. * * @type {import('../platform/graphics/texture.js').Texture} */ @@ -548,12 +599,17 @@ class Scene extends EventHandler { } } + /** + * Gets the base cubemap texture used as the scene's skybox when skyboxMip is 0. + * + * @type {import('../platform/graphics/texture.js').Texture} + */ get skybox() { return this._skyboxCubeMap; } /** - * Multiplier for skybox intensity. Defaults to 1. Unused if physical units are used. + * Sets the multiplier for skybox intensity. Defaults to 1. Unused if physical units are used. * * @type {number} */ @@ -564,12 +620,17 @@ class Scene extends EventHandler { } } + /** + * Gets the multiplier for skybox intensity. + * + * @type {number} + */ get skyboxIntensity() { return this._skyboxIntensity; } /** - * Luminance (in lm/m^2) of skybox. Defaults to 0. Only used if physical units are used. + * Sets the luminance (in lm/m^2) of the skybox. Defaults to 0. Only used if physical units are used. * * @type {number} */ @@ -580,12 +641,17 @@ class Scene extends EventHandler { } } + /** + * Gets the luminance (in lm/m^2) of the skybox. + * + * @type {number} + */ get skyboxLuminance() { return this._skyboxLuminance; } /** - * The mip level of the skybox to be displayed. Only valid for prefiltered cubemap skyboxes. + * Sets the mip level of the skybox to be displayed. Only valid for prefiltered cubemap skyboxes. * Defaults to 0 (base level). * * @type {number} @@ -597,12 +663,17 @@ class Scene extends EventHandler { } } + /** + * Gets the mip level of the skybox to be displayed. + * + * @type {number} + */ get skyboxMip() { return this._skyboxMip; } /** - * The rotation of the skybox to be displayed. Defaults to {@link Quat.IDENTITY}. + * Sets the rotation of the skybox to be displayed. Defaults to {@link Quat.IDENTITY}. * * @type {Quat} */ @@ -627,12 +698,17 @@ class Scene extends EventHandler { } } + /** + * Gets the rotation of the skybox to be displayed. + * + * @type {Quat} + */ get skyboxRotation() { return this._skyboxRotation; } /** - * The tonemapping transform to apply when writing fragments to the frame buffer. Can be: + * Sets the tonemapping transform to apply when writing fragments to the frame buffer. Can be: * * - {@link TONEMAP_LINEAR} * - {@link TONEMAP_FILMIC} @@ -652,6 +728,11 @@ class Scene extends EventHandler { } } + /** + * Gets the tonemapping transform to apply when writing fragments to the frame buffer. + * + * @type {number} + */ get toneMapping() { return this._toneMapping; } @@ -785,7 +866,7 @@ class Scene extends EventHandler { } /** - * The lightmap pixel format. + * Gets the lightmap pixel format. * * @type {number} */ diff --git a/src/scene/sprite.js b/src/scene/sprite.js index a239e0dbb08..88389cc0a8c 100644 --- a/src/scene/sprite.js +++ b/src/scene/sprite.js @@ -69,7 +69,7 @@ class Sprite extends EventHandler { } /** - * The keys of the frames in the sprite atlas that this sprite is using. + * Sets the keys of the frames in the sprite atlas that this sprite is using. * * @type {string[]} */ @@ -87,12 +87,17 @@ class Sprite extends EventHandler { this.fire('set:frameKeys', value); } + /** + * Gets the keys of the frames in the sprite atlas that this sprite is using. + * + * @type {string[]} + */ get frameKeys() { return this._frameKeys; } /** - * The texture atlas. + * Sets the texture atlas. * * @type {import('./texture-atlas.js').TextureAtlas} */ @@ -121,12 +126,17 @@ class Sprite extends EventHandler { this.fire('set:atlas', value); } + /** + * Gets the texture atlas. + * + * @type {import('./texture-atlas.js').TextureAtlas} + */ get atlas() { return this._atlas; } /** - * The number of pixels that map to one PlayCanvas unit. + * Sets the number of pixels that map to one PlayCanvas unit. * * @type {number} */ @@ -146,12 +156,17 @@ class Sprite extends EventHandler { } } + /** + * Gets the number of pixels that map to one PlayCanvas unit. + * + * @type {number} + */ get pixelsPerUnit() { return this._pixelsPerUnit; } /** - * The rendering mode of the sprite. Can be: + * Sets the rendering mode of the sprite. Can be: * * - {@link SPRITE_RENDERMODE_SIMPLE} * - {@link SPRITE_RENDERMODE_SLICED} @@ -179,6 +194,11 @@ class Sprite extends EventHandler { } } + /** + * Sets the rendering mode of the sprite. + * + * @type {number} + */ get renderMode() { return this._renderMode; } diff --git a/src/scene/texture-atlas.js b/src/scene/texture-atlas.js index e65ed10238a..7e7224c1350 100644 --- a/src/scene/texture-atlas.js +++ b/src/scene/texture-atlas.js @@ -45,7 +45,7 @@ class TextureAtlas extends EventHandler { } /** - * The texture used by the atlas. + * Sets the texture used by the atlas. * * @type {import('../platform/graphics/texture.js').Texture} */ @@ -54,12 +54,17 @@ class TextureAtlas extends EventHandler { this.fire('set:texture', value); } + /** + * Gets the texture used by the atlas. + * + * @type {import('../platform/graphics/texture.js').Texture} + */ get texture() { return this._texture; } /** - * Contains frames which define portions of the texture atlas. + * Sets the frames which define portions of the texture atlas. * * @type {object} */ @@ -68,6 +73,11 @@ class TextureAtlas extends EventHandler { this.fire('set:frames', value); } + /** + * Gets the frames which define portions of the texture atlas. + * + * @type {object} + */ get frames() { return this._frames; } diff --git a/tsconfig.json b/tsconfig.json index 93aa0128c48..691968a1088 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -22,29 +22,6 @@ }, "entryPoints": [ "./src/index.js" ], "excludeNotDocumented": true, - "excludeNotDocumentedKinds": [ - "Module", - "Namespace", - "Enum", - // "EnumMember", // Not enabled by default - "Variable", - "Function", - "Class", - "Interface", - "Constructor", - "Property", - "Method", - "CallSignature", - "IndexSignature", - "ConstructorSignature", - "Accessor", - // We only document getters/setters with one JSDoc block so if there is a setter, - // the getter will appear undocumented (setters always appear before getters). - // "GetSignature", - "SetSignature", - "TypeAlias", - "Reference" - ], "githubPages": false, "name": "PlayCanvas Engine API", "navigationLinks": {