diff --git a/examples/src/examples/loaders/gsplat-many.example.mjs b/examples/src/examples/loaders/gsplat-many.example.mjs index ecc108664ef..7c4134b8923 100644 --- a/examples/src/examples/loaders/gsplat-many.example.mjs +++ b/examples/src/examples/loaders/gsplat-many.example.mjs @@ -75,7 +75,6 @@ assetListLoader.load(() => { const createSplatInstance = (name, resource, px, py, pz, scale, vertex, fragment) => { const splat = resource.instantiate({ - debugRender: false, fragment: fragment, vertex: vertex }); diff --git a/examples/src/examples/loaders/gsplat.example.mjs b/examples/src/examples/loaders/gsplat.example.mjs index 83b2bcbcce1..0e9b2153773 100644 --- a/examples/src/examples/loaders/gsplat.example.mjs +++ b/examples/src/examples/loaders/gsplat.example.mjs @@ -67,7 +67,6 @@ assetListLoader.load(() => { const createSplatInstance = (resource, px, py, pz, scale, vertex, fragment) => { const splat = resource.instantiate({ - debugRender: false, fragment: fragment, vertex: vertex }); diff --git a/src/core/math/color.js b/src/core/math/color.js index 346a4ddd063..4cdbd1334ce 100644 --- a/src/core/math/color.js +++ b/src/core/math/color.js @@ -1,7 +1,11 @@ import { math } from './math.js'; /** - * Representation of an RGBA color. + * An RGBA color. + * + * Each color component is a floating point value in the range 0 to 1. The `r` (red), `g` (green) + * and `b` (blue) components define a color in RGB color space. The `a` (alpha) component defines + * transparency. An alpha of 1 is fully opaque. An alpha of 0 is fully transparent. * * @category Math */ diff --git a/src/framework/components/element/component.js b/src/framework/components/element/component.js index 46397f3d6c4..7f52ea5e4cd 100644 --- a/src/framework/components/element/component.js +++ b/src/framework/components/element/component.js @@ -31,7 +31,7 @@ const matC = new Mat4(); const matD = new Mat4(); /** - * ElementComponents are used to construct user interfaces. An ElementComponent's [type](#type) + * ElementComponents are used to construct user interfaces. The {@link ElementComponent#type} * property can be configured in 3 main ways: as a text element, as an image element or as a group * element. If the ElementComponent has a {@link ScreenComponent} ancestor in the hierarchy, it * will be transformed with respect to the coordinate system of the screen. If there is no @@ -69,6 +69,7 @@ const matD = new Mat4(); * ``` * * Relevant 'Engine-only' examples: + * * - [Basic text rendering](https://playcanvas.github.io/#/user-interface/text) * - [Auto font sizing](https://playcanvas.github.io/#/user-interface/text-auto-font-size) * - [Emojis](https://playcanvas.github.io/#/user-interface/text-emojis) diff --git a/src/framework/components/gsplat/component.js b/src/framework/components/gsplat/component.js index 818ff1053da..847315efd34 100644 --- a/src/framework/components/gsplat/component.js +++ b/src/framework/components/gsplat/component.js @@ -4,7 +4,14 @@ import { AssetReference } from '../../asset/asset-reference.js'; import { Component } from '../component.js'; /** - * Enables an Entity to render a Gaussian Splat (asset of the 'gsplat' type). + * The GSplatComponent enables an {@link Entity} to render 3D Gaussian Splats. Splats are always + * loaded from {@link Asset}s rather than being created programmatically. The asset type is + * `gsplat` which are in the `.ply` file format. + * + * Relevant examples: + * + * - [Loading a Splat](https://playcanvas.github.io/#/loaders/gsplat) + * - [Custom Splat Shaders](https://playcanvas.github.io/#/loaders/gsplat-many) * * @category Graphics */ diff --git a/src/framework/components/render/component.js b/src/framework/components/render/component.js index e9885b66168..f20c87c51b0 100644 --- a/src/framework/components/render/component.js +++ b/src/framework/components/render/component.js @@ -15,8 +15,44 @@ import { Component } from '../component.js'; import { EntityReference } from '../../utils/entity-reference.js'; /** - * Enables an Entity to render a {@link Mesh} or a primitive shape. This component attaches - * {@link MeshInstance} geometry to the Entity. + * The RenderComponent enables an {@link Entity} to render 3D meshes. The {@link RenderComponent#type} + * property can be set to one of several predefined shape types (such as `box`, `sphere`, `cone` + * and so on). Alternatively, the component can be configured to manage an arbitrary array of + * {@link MeshInstance} objects. These can either be created programmatically or loaded from an + * {@link Asset}. + * + * You should never need to use the RenderComponent constructor directly. To add a RenderComponent + * to an Entity, use {@link Entity#addComponent}: + * + * ```javascript + * // Add a render component to an entity with the default options + * const entity = new pc.Entity(); + * entity.addComponent("render"); // This defaults to a 1x1x1 box + * ``` + * + * To create an entity with a specific primitive shape: + * + * ```javascript + * entity.addComponent("render", { + * type: "cone", + * castShadows: false, + * receiveShadows: false + * }); + * ``` + * + * Once the RenderComponent is added to the entity, you can set and get any of its properties: + * + * ```javascript + * entity.render.type = 'capsule'; // Set the render component's type + * + * console.log(entity.render.type); // Get the render component's type and print it + * ``` + * + * Relevant examples: + * + * - [Spinning Cube](https://playcanvas.github.io/#/misc/hello-world) + * - [Primitive Shapes](https://playcanvas.github.io/#/graphics/shapes) + * - [Loading Render Assets](https://playcanvas.github.io/#/graphics/render-asset) * * @property {import('../../entity.js').Entity} rootBone A reference to the entity to be used as * the root bone for any skinned meshes that are rendered by this component. diff --git a/src/framework/components/sound/component.js b/src/framework/components/sound/component.js index 4813c7b60df..948c4a89460 100644 --- a/src/framework/components/sound/component.js +++ b/src/framework/components/sound/component.js @@ -7,7 +7,48 @@ import { Component } from '../component.js'; import { SoundSlot } from './slot.js'; /** - * The Sound Component controls playback of {@link Sound}s. + * The SoundComponent enables an {@link Entity} to play audio. The SoundComponent can manage + * multiple {@link SoundSlot}s, each of which can play a different audio asset with its own set + * of properties such as volume, pitch, and looping behavior. + * + * The SoundComponent supports positional audio, meaning that the sound can be played relative + * to the Entity's position in 3D space. This is useful for creating immersive audio experiences + * where the sound's volume and panning are affected by the listener's position and orientation. + * Positional audio requires that an Entity with an {@link AudioListenerComponent} be added to the + * scene. + * + * You should never need to use the SoundComponent constructor directly. To add a SoundComponent + * to an Entity, use {@link Entity#addComponent}: + * + * ```javascript + * // Add a sound component to an entity + * const entity = new pc.Entity(); + * entity.addComponent("sound"); + * ``` + * + * Then, to add a sound slot to the component: + * + * ```javascript + * entity.sound.addSlot("beep", { + * asset: asset, + * autoPlay: true, + * loop: true, + * overlap: true, + * pitch: 1.5 + * }); + * ``` + * + * Once the SoundComponent is added to the entity, you can set and get any of its properties: + * + * ```javascript + * entity.sound.volume = 0.8; // Set the volume for all sounds + * + * console.log(entity.sound.volume); // Get the volume and print it + * ``` + * + * Relevant examples: + * + * - [Positional Sound](https://playcanvas.github.io/#/sound/positional) * * @category Sound */ diff --git a/src/framework/xr/xr-manager.js b/src/framework/xr/xr-manager.js index 9f6ae9a2691..c38e6b49d6b 100644 --- a/src/framework/xr/xr-manager.js +++ b/src/framework/xr/xr-manager.js @@ -804,7 +804,7 @@ class XrManager extends EventHandler { const deviceType = device.deviceType; if ((deviceType === DEVICETYPE_WEBGL1 || deviceType === DEVICETYPE_WEBGL2) && window.XRWebGLBinding) { try { - this.webglBinding = new XRWebGLBinding(this._session, device.gl); // eslint-disable-line no-undef + this.webglBinding = new XRWebGLBinding(this._session, device.gl); } catch (ex) { this.fire('error', ex); } diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 07a93201ba4..cba2c387189 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -87,7 +87,15 @@ function findNode(node, test) { */ /** - * A hierarchical scene node. + * The `GraphNode` class represents a node within a hierarchical scene graph. Each `GraphNode` can + * reference a array of child nodes. This creates a tree-like structure that is fundamental for + * organizing and managing the spatial relationships between objects in a 3D scene. This class + * provides a comprehensive API for manipulating the position, rotation, and scale of nodes both + * locally and in world space. + * + * `GraphNode` is the superclass of {@link Entity}, which is the primary class for creating objects + * in a PlayCanvas application. For this reason, `GraphNode` is rarely used directly, but it provides + * a powerful set of features that are leveraged by the `Entity` class. */ class GraphNode extends EventHandler { /**