From 73f7583f2bb28e906853162ac97234aa7ef461d8 Mon Sep 17 00:00:00 2001 From: KPal Date: Fri, 31 Jul 2026 14:40:39 +0100 Subject: [PATCH 01/10] docs: document API behaviours that fail silently for agents Auditing the engine against transcripts of autonomous agents building games from scratch surfaced a class of APIs whose obvious usage compiles, runs, and produces nothing, with no error and no warning to trace back from. Each of these is documented where the reader already is, so the correction arrives at the point of use and ships in playcanvas.d.ts. - ShaderMaterial: attributes is documented as optional, but omitting it throws once the material reaches a skinned or morphed mesh, since the generated skinning attributes are merged into the supplied object - StandardMaterial#gloss: the glTF importer enables glossInvert, so the same assignment means the opposite on an imported material - CameraFrame: the example produced no bloom at all. ScriptComponent#create shallow-assigns properties, replacing a whole attribute group and dropping its enabled flag, which every group but rendering is gated on - Keyboard: key state comes from the legacy keyCode, which a hand-built KeyboardEvent leaves at 0; and wasPressed/wasReleased compare against a once-per-frame snapshot, so a down/up pair in one task is seen by neither - Asset#ready: a failed load still marks the asset loaded but fires error rather than load, so the callback never runs and an await never settles - LightComponent#castShadows: directional shadows stop at shadowDistance, which defaults to 40, with nothing at the point of use to say so - AppBase#setCanvasFillMode: claimed it resizes when the window changes; the engine installs no resize listener anywhere - LayerComposition#push: the default composition ends with the UI layer, so a pushed layer renders after the UI and outside post-processing - GraphNode#addChild: the child's local transform is reinterpreted against the new parent, so a node placed in world space first appears to move - GraphNode#removeChild: detaching does not deactivate; lights, cameras and scripts keep running while enabled still reads true - GraphNode#lookAt: an up vector parallel to the view direction leaves the node unrotated rather than reporting anything - RenderComponent#material: type 'asset' is what instantiateRenderEntity always produces, so the setter is inert for every model from a container Comment-only; no signatures or behaviour change. --- scripts/esm/camera-frame.mjs | 15 +++++++++------ src/framework/app-base.js | 5 ++++- src/framework/asset/asset.js | 4 ++++ src/framework/components/light/component.js | 4 ++++ src/framework/components/render/component.js | 5 ++++- src/platform/input/keyboard.js | 8 ++++++++ src/scene/composition/layer-composition.js | 5 +++++ src/scene/graph-node.js | 13 +++++++++++++ src/scene/materials/shader-material.js | 4 +++- src/scene/materials/standard-material.js | 2 ++ 10 files changed, 56 insertions(+), 9 deletions(-) diff --git a/scripts/esm/camera-frame.mjs b/scripts/esm/camera-frame.mjs index 71dd2c502de..08548f373fa 100644 --- a/scripts/esm/camera-frame.mjs +++ b/scripts/esm/camera-frame.mjs @@ -633,15 +633,18 @@ class VolumetricFog { * of field and volumetric fog. * * Attach the script to an entity with a camera component and adjust the attribute groups to - * configure the post-processing stack. + * configure the post-processing stack. Every group except `rendering` is gated by its own + * `enabled` flag, which defaults to false. + * + * Set the fields on the groups after creating the script. Do not pass a group through the + * `properties` argument of {@link ScriptComponent#create}: that assignment is shallow, so it + * replaces the whole group object and drops its `enabled` flag, leaving the effect switched off. * * @example * cameraEntity.addComponent('script'); - * cameraEntity.script.create(CameraFrame, { - * properties: { - * bloom: { intensity: 0.02 } - * } - * }); + * const cameraFrame = cameraEntity.script.create(CameraFrame); + * cameraFrame.bloom.enabled = true; + * cameraFrame.bloom.intensity = 0.02; * @category Post-Processing */ class CameraFrame extends Script { diff --git a/src/framework/app-base.js b/src/framework/app-base.js index 327621a0caf..d8700afd171 100644 --- a/src/framework/app-base.js +++ b/src/framework/app-base.js @@ -1174,7 +1174,10 @@ class AppBase extends EventHandler { } /** - * Controls how the canvas fills the window and resizes when the window changes. + * Controls how the canvas fills the window. The canvas is sized when this is called and on + * every {@link AppBase#resizeCanvas}; the engine installs no window `resize` listener of its + * own, so call `resizeCanvas` from your own handler to keep the window-relative modes tracking + * the window. * * @param {string} mode - The mode to use when setting the size of the canvas. Can be: * diff --git a/src/framework/asset/asset.js b/src/framework/asset/asset.js index 70086c9f2f8..6bc379fc96d 100644 --- a/src/framework/asset/asset.js +++ b/src/framework/asset/asset.js @@ -554,6 +554,10 @@ class Asset extends EventHandler { * Take a callback which is called as soon as the asset is loaded. If the asset is already * loaded the callback is called straight away. * + * The callback fires on success only. A failed load still marks the asset as loaded, but fires + * `error` rather than `load`, so this callback never runs — listen for the `error` event as + * well whenever a failure has to be handled, and never await this callback alone. + * * @param {AssetReadyCallback} callback - The function called when the asset is ready. Passed * the (asset) arguments. * @param {object} [scope] - Scope object to use when calling the callback. diff --git a/src/framework/components/light/component.js b/src/framework/components/light/component.js index 902dd3f00f9..20782ffebcb 100644 --- a/src/framework/components/light/component.js +++ b/src/framework/components/light/component.js @@ -389,6 +389,10 @@ class LightComponent extends Component { /** * Sets whether the light will cast shadows. Defaults to false. * + * For a directional light, shadows are only rendered out to + * {@link LightComponent#shadowDistance} from the viewpoint, which defaults to 40. Size that to + * the area the camera actually sees, or shadows simply stop appearing beyond it. + * * @type {boolean} */ set castShadows(value) { diff --git a/src/framework/components/render/component.js b/src/framework/components/render/component.js index e173ddc014a..5472e6f4596 100644 --- a/src/framework/components/render/component.js +++ b/src/framework/components/render/component.js @@ -594,7 +594,10 @@ class RenderComponent extends Component { /** * Sets the material {@link Material} that will be used to render the component. The material - * is ignored for renders of type 'asset'. + * is ignored for renders of type 'asset' — which is the type every entity produced by + * `instantiateRenderEntity` carries, so this setter has no effect on models loaded from a + * container. For those, assign `material` on each entry of + * {@link RenderComponent#meshInstances} instead. * * @type {Material} */ diff --git a/src/platform/input/keyboard.js b/src/platform/input/keyboard.js index 7fd9574a935..e1b301c10ec 100644 --- a/src/platform/input/keyboard.js +++ b/src/platform/input/keyboard.js @@ -59,6 +59,14 @@ const _keyCodeToKeyIdentifier = { * changes and window blur events by clearing key states. The Keyboard instance must be attached to * a DOM element before it can detect key events. * + * Key state is derived from the legacy `KeyboardEvent.keyCode` property. Browsers populate it for + * real input, but a hand-constructed `new KeyboardEvent(...)` leaves it at 0, so synthesized events + * must set `keyCode` explicitly in order to be observed. + * + * {@link Keyboard#wasPressed} and {@link Keyboard#wasReleased} compare against a snapshot taken + * once per frame, so a keydown and keyup delivered within the same task are seen by neither. Hold + * the key across at least one frame. + * * Your application's Keyboard instance is managed and accessible via {@link AppBase#keyboard}. * * @category Input diff --git a/src/scene/composition/layer-composition.js b/src/scene/composition/layer-composition.js index 6095cf917c6..1868f1a0bf9 100644 --- a/src/scene/composition/layer-composition.js +++ b/src/scene/composition/layer-composition.js @@ -403,6 +403,11 @@ class LayerComposition extends EventHandler { /** * Adds a layer (both opaque and semi-transparent parts) to the end of the {@link layerList}. * + * The default composition ends with the UI layer, so a layer pushed here renders after the UI + * and after the last layer a camera's post-processing applies to. To place a layer inside the + * post-processed range instead, use {@link LayerComposition#insert} with an index from + * {@link LayerComposition#getOpaqueIndex}. + * * @param {Layer} layer - A {@link Layer} to add. */ push(layer) { diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index d4d6f0b0a24..751d1d0313d 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -1337,6 +1337,10 @@ class GraphNode extends EventHandler { * Add a new child to the child list and update the parent value of the child node. * If the node already had a parent, it is removed from its child list. * + * The child keeps its existing local transform, which is now interpreted relative to the new + * parent, so a node placed in world space before being added will appear to move. Set the + * transform after adding, or re-apply the world placement with {@link GraphNode#setPosition}. + * * @param {GraphNode} node - The new child to add. * @example * const e = new Entity(app); @@ -1473,6 +1477,10 @@ class GraphNode extends EventHandler { /** * Remove the node from the child list and update the parent value of the child. * + * This detaches the node without disabling it: the removed subtree still reports + * `enabled === true`, and its lights, cameras, scripts and sounds keep running. Set + * `enabled = false` to deactivate a node, or destroy the entity to remove it outright. + * * @param {GraphNode} child - The node to remove. * @example * const child = this.entity.children[0]; @@ -1591,6 +1599,11 @@ class GraphNode extends EventHandler { /** * Reorients the graph node so that the negative z-axis points towards the target. * + * The up vector must not be parallel to the direction from the node to the target. When it is — + * looking straight up or down with the default up vector, or at the node's own position — the + * basis is degenerate and the node is left unrotated, with nothing reported. Pass a different + * up vector in those cases. + * * @overload * @param {number} x - X-component of the world space coordinate to look at. * @param {number} y - Y-component of the world space coordinate to look at. diff --git a/src/scene/materials/shader-material.js b/src/scene/materials/shader-material.js index a4ef9494785..e80474ed395 100644 --- a/src/scene/materials/shader-material.js +++ b/src/scene/materials/shader-material.js @@ -21,7 +21,9 @@ import { Material } from './material.js'; * @property {string} [fragmentWGSL] - The fragment shader code in WGSL. * @property {Object} [attributes] - Object detailing the mapping of vertex shader * attribute names to semantics SEMANTIC_*. This enables the engine to match vertex buffer data as - * inputs to the shader. Defaults to undefined, which generates the default attributes. + * inputs to the shader. Defaults to undefined, which generates the default attributes. Must be + * supplied when the material is applied to a skinned or morphed mesh, as the skinning and morph + * attributes the engine adds automatically are merged into this object. * @property {string | string[]} [fragmentOutputTypes] - Fragment shader output types, which default to * vec4. Passing a string will set the output type for all color attachments. Passing an array will * set the output type for each color attachment. @see ShaderDefinitionUtils.createDefinition diff --git a/src/scene/materials/standard-material.js b/src/scene/materials/standard-material.js index c8f725e914c..573779c382a 100644 --- a/src/scene/materials/standard-material.js +++ b/src/scene/materials/standard-material.js @@ -247,6 +247,8 @@ const isBlack = (color) => { * @property {string} metalnessVertexColorChannel Vertex color channel to use for metalness. Can be * "r", "g", "b" or "a". * @property {number} gloss Defines the glossiness of the material from 0 (rough) to 1 (shiny). + * Materials imported from glTF enable {@link StandardMaterial#glossInvert}, which reverses this: + * on those materials gloss holds roughness, so 0 is shiny and 1 is rough. * @property {Texture|null} glossMap Gloss map (default is null). If specified, will be multiplied * by normalized gloss value and/or vertex colors. * @property {boolean} glossInvert Invert the gloss component (default is false). Enabling this From b8ecedb01d23f4c37f6c6acf410bf602fb3336be Mon Sep 17 00:00:00 2001 From: KPal Date: Fri, 31 Jul 2026 16:09:20 +0100 Subject: [PATCH 02/10] docs: anchor entry-point classes to the current API Each of these classes is where a reader forms a plan before reaching any member's documentation, and each has a pre-2.x idiom that still parses: scene-wide tone mapping, a bare AppBase construction, input devices assumed present, and material properties assumed live without update(). The StandardMaterial note is the one with a silent failure behind it. Uniforms are recomputed only in updateUniforms, which prepareForRender calls only when _preparedVersion differs from _updateVersion (material.js:773). Fields start at _updateVersion = 0 and _preparedVersion = -1 and only update() increments the former, so exactly one upload happens on first render and every later property change is dropped until update() runs. --- src/framework/app-base.js | 5 +++++ src/framework/application.js | 5 +++++ src/scene/materials/standard-material.js | 6 ++++++ src/scene/scene.js | 7 +++++++ 4 files changed, 23 insertions(+) diff --git a/src/framework/app-base.js b/src/framework/app-base.js index d8700afd171..a23559277d5 100644 --- a/src/framework/app-base.js +++ b/src/framework/app-base.js @@ -114,6 +114,11 @@ let app = null; * {@link ResourceHandler}s yourself. This facilitates * [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) when bundling * your application. + * + * `new AppBase(canvas)` only constructs the instance and its root entity. You must then call + * {@link AppBase#init} with an {@link AppOptions} supplying at minimum `graphicsDevice`, + * `componentSystems` and `resourceHandlers` before adding components or calling + * {@link AppBase#start}. {@link Application} assembles those options for you. */ class AppBase extends EventHandler { /** diff --git a/src/framework/application.js b/src/framework/application.js index 4bf0598d438..03be51f2534 100644 --- a/src/framework/application.js +++ b/src/framework/application.js @@ -70,6 +70,11 @@ import { XrManager } from './xr/xr-manager.js'; * {@link ComponentSystem}s and {@link ResourceHandler}s implemented in the PlayCanvas Engine. This * makes app setup simple but results in the full engine being included when bundling your * application. + * + * {@link AppBase#keyboard}, {@link AppBase#mouse}, {@link AppBase#touch}, + * {@link AppBase#gamepads} and {@link AppBase#elementInput} stay `null` unless the matching device + * is passed to this constructor, so a game that reads input must construct with, for example, + * `{ keyboard: new Keyboard(window), mouse: new Mouse(canvas), touch: new TouchDevice(canvas) }`. */ class Application extends AppBase { /** diff --git a/src/scene/materials/standard-material.js b/src/scene/materials/standard-material.js index 573779c382a..e1078dc37c6 100644 --- a/src/scene/materials/standard-material.js +++ b/src/scene/materials/standard-material.js @@ -61,6 +61,12 @@ const isBlack = (color) => { * Most maps can use 3 types of input values in any combination: constant ({@link Color} or number), * mesh vertex colors and a {@link Texture}. All enabled inputs are multiplied together. * + * A property assignment only reaches the GPU once {@link Material#update} is called. The uniform + * values below are recomputed solely inside `updateUniforms`, which the renderer skips unless + * `update()` has incremented the material's update version since the last render — so a `diffuse` + * or `emissive` change made after the material's first frame is silently ignored until + * `material.update()` runs. + * * @property {Color} ambient The ambient color of the material. This color value is 3-component * (RGB), where each component is between 0 and 1. * @property {Color} diffuse The diffuse color of the material. This color value is 3-component diff --git a/src/scene/scene.js b/src/scene/scene.js index af5fed15642..e6178624674 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -28,6 +28,13 @@ import { getDefaultMaterial } from './materials/default-material.js'; * A scene is a graphical representation of an environment. It manages the scene hierarchy, all * graphical objects, lights, and scene-wide properties. * + * Tone mapping and gamma correction are configured per camera, not on the scene: use + * {@link CameraComponent#toneMapping} and {@link CameraComponent#gammaCorrection}. `Scene` has no + * such properties and no deprecation shim, so assigning to them silently does nothing. Fog remains + * scene-wide, but {@link Scene#fog} is a read-only {@link FogParams} object rather than a mode + * constant — set its `type`, `color`, `start` and `end` — and {@link CameraComponent#fog} can + * override it for a single camera. + * * @category Graphics */ class Scene extends EventHandler { From c0540a0d5350813cee8c167d5667a3bed8fb3e2b Mon Sep 17 00:00:00 2001 From: KPal Date: Fri, 31 Jul 2026 16:16:11 +0100 Subject: [PATCH 03/10] docs: cross-reference in-package capability from where it is needed The package ships ~34 production scripts under scripts/esm/**, an input-source layer, debug and profiler builds, and per-module build trees, none of which were referenced from any doc a reader passes through on the way to needing them. Neither "playcanvas/scripts" nor "playcanvas/debug" appeared anywhere in src/ or README.md. Each pointer is added to the block the reader is already in. No @ignore tag is added or removed; ignored targets (EnvLighting, AppBase#stats) are named in plain text rather than linked. Changing the pre-existing {@link AppBase#stats} in MiniStats to backticks fixes a link that pointed at an @ignore'd target, taking typedoc warnings from 37 to 36. Claims were checked against the scripts rather than assumed, which corrected three of them: the character controllers have no crouch, so that is not claimed; the .obj and .spz parsers register via getHandler(type).addParser() rather than addHandler(), so the note sits on the ResourceLoader class block and names the real call; and XrManipulation is two-handed world drag/rotate/ scale rather than generic object grabbing. The worldToScreen z-sign claim was verified numerically: behind-camera points yield negative clip z and w. --- README.md | 11 +++++++++++ src/core/debug.js | 4 ++++ src/core/tracing.js | 4 ++++ src/extras/mini-stats/mini-stats.js | 6 +++++- src/framework/components/camera/component.js | 9 +++++++++ src/framework/components/camera/post-effect-queue.js | 5 ++++- src/framework/components/rigid-body/component.js | 5 +++++ src/framework/handlers/loader.js | 7 +++++++ src/framework/script/script.js | 6 ++++++ src/framework/xr/xr-manager.js | 6 ++++++ src/platform/input/game-pads.js | 4 ++++ src/platform/input/keyboard.js | 5 +++++ src/platform/input/mouse.js | 5 +++++ src/scene/scene.js | 10 +++++++++- 14 files changed, 84 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f27cba3f65..e9f95666a1e 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,12 @@ app.on('update', dt => box.rotate(10 * dt, 20 * dt, 30 * dt)); app.start(); ``` +Elsewhere in your code, or from the browser console, retrieve the running application with +`Application.getApplication()`. You do not need to assign it to `window` yourself. + +Ready-made `Script` classes — camera and character controllers, post-processing, water, sky, XR and +more — ship in the same package under the `playcanvas/scripts/esm/` subpath. + Want to play with the code yourself? Edit it on [CodePen](https://codepen.io/playcanvas/pen/NPbxMj). A full guide to setting up a local development environment based on the PlayCanvas Engine can be found [here](https://developer.playcanvas.com/user-manual/engine/standalone/). @@ -139,3 +145,8 @@ Now you can run various build options: | ------- | ----------- | ---------- | | `npm run build` | Build all engine flavors and type declarations | `build` | | `npm run docs` | Build engine [API reference docs](https://api.playcanvas.com/engine/) | `docs` | + +The ESM builds are emitted as per-module trees — `build/playcanvas/src/**`, +`build/playcanvas.dbg/src/**` and `build/playcanvas.prf/src/**` — mirroring `src/` one file per +module, each with its own `.d.ts`. These ship in the npm package and are the easiest way to read +engine source or types for a single class without loading the whole `playcanvas.d.ts` bundle. diff --git a/src/core/debug.js b/src/core/debug.js index df7fccd4418..13ffcb5a96d 100644 --- a/src/core/debug.js +++ b/src/core/debug.js @@ -3,6 +3,10 @@ import { Tracing } from './tracing.js'; /** * Engine debug log system. Note that the logging only executes in the debug build of the engine, * and is stripped out in other builds. + * + * The debug build ships in the npm package: import from `'playcanvas/debug'` instead of + * `'playcanvas'` to enable assertions, deprecation notices and validation warnings. A + * `'playcanvas/profiler'` build is also available for per-frame timings. */ class Debug { /** diff --git a/src/core/tracing.js b/src/core/tracing.js index 4310fafbdb8..8eaa31f4541 100644 --- a/src/core/tracing.js +++ b/src/core/tracing.js @@ -3,6 +3,10 @@ * Note that the trace logging only takes place in the debug build of the engine and is stripped * out in other builds. * + * The debug build ships in the npm package: import from `'playcanvas/debug'` instead of + * `'playcanvas'` to enable trace channels, assertions and validation warnings. A + * `'playcanvas/profiler'` build is also available for per-frame timings. + * * @category Debug */ class Tracing { diff --git a/src/extras/mini-stats/mini-stats.js b/src/extras/mini-stats/mini-stats.js index ad85cd46128..aea5906efad 100644 --- a/src/extras/mini-stats/mini-stats.js +++ b/src/extras/mini-stats/mini-stats.js @@ -75,7 +75,11 @@ const delayedStartStats = new Set([ /** * MiniStats is a small graphical overlay that displays realtime performance metrics. By default, * it shows CPU and GPU utilization, frame timings and draw call count. It can also be configured - * to display additional graphs based on data collected into {@link AppBase#stats}. + * to display additional graphs based on data collected into `AppBase#stats`. + * + * Detailed per-frame sub-timings — render, script, anim and physics — are only populated in the + * profiler build; import from `'playcanvas/profiler'` to obtain them. In other builds those + * counters read zero. */ class MiniStats { /** diff --git a/src/framework/components/camera/component.js b/src/framework/components/camera/component.js index f3fda9c8969..75e29762039 100644 --- a/src/framework/components/camera/component.js +++ b/src/framework/components/camera/component.js @@ -61,6 +61,10 @@ import { PostEffectQueue } from './post-effect-queue.js'; * console.log(entity.camera.nearClip); // Get the near clip of the camera * ``` * + * For ready-made camera behaviour, attach the `CameraControls` script from + * `playcanvas/scripts/esm/camera-controls.mjs`, which provides orbit, fly and pan driven by mouse, + * touch and gamepad input. + * * Relevant Engine API examples: * * - [First Person Camera](https://playcanvas.github.io/#/camera/first-person) @@ -1149,6 +1153,11 @@ class CameraComponent extends Component { /** * Convert a point from 3D world space to 2D screen space. * + * A returned `z` of zero or less means the point is behind the camera and the x and y values + * are not meaningful. For DOM labels anchored to world positions, + * `playcanvas/scripts/esm/annotations.mjs` provides `Annotation` and `AnnotationManager`, + * which handle behind-camera rejection and occlusion fading. + * * @param {Vec3} worldCoord - The world space coordinate. * @param {Vec3} [screenCoord] - 3D vector to receive screen coordinate result. * @returns {Vec3} The screen space coordinate. diff --git a/src/framework/components/camera/post-effect-queue.js b/src/framework/components/camera/post-effect-queue.js index d7dbb318fbf..dd6c055c156 100644 --- a/src/framework/components/camera/post-effect-queue.js +++ b/src/framework/components/camera/post-effect-queue.js @@ -20,7 +20,10 @@ class PostEffectEntry { } /** - * Used to manage multiple post effects for a camera. + * Used to manage multiple post effects for a camera. This is the legacy post-processing path. For + * new work use {@link CameraFrame}, which implements bloom, SSAO, depth of field, TAA, volumetric + * fog and tone mapping as one HDR pipeline; `playcanvas/scripts/esm/camera-frame.mjs` wraps it as + * an attachable script. * * @category Graphics */ diff --git a/src/framework/components/rigid-body/component.js b/src/framework/components/rigid-body/component.js index 9afb625aa3b..791a2e66e81 100644 --- a/src/framework/components/rigid-body/component.js +++ b/src/framework/components/rigid-body/component.js @@ -58,6 +58,11 @@ const _vecB = new Vec3(); * console.log(entity.rigidbody.mass); * ``` * + * For player movement, `playcanvas/scripts/esm/first-person-controller.mjs` and + * `playcanvas/scripts/esm/third-person-controller.mjs` ship complete rigidbody character + * controllers with capsule collision, damped ground and air movement, sprinting, jumping and + * camera control. Attach one instead of driving the body by hand. + * * Relevant Engine API examples: * * - [Falling shapes](https://playcanvas.github.io/#/physics/falling-shapes) diff --git a/src/framework/handlers/loader.js b/src/framework/handlers/loader.js index 36f216daf67..15041e38e97 100644 --- a/src/framework/handlers/loader.js +++ b/src/framework/handlers/loader.js @@ -20,6 +20,13 @@ import { http } from '../../platform/net/http.js'; /** * Load resource data, potentially from remote sources. Caches resource on load to prevent multiple * requests. Add ResourceHandlers to handle different types of resources. + * + * Parsers for formats the engine does not load by default ship in the package and are registered + * on an existing handler rather than added as one: + * `playcanvas/scripts/esm/parsers/obj-model.mjs` adds `.obj` model loading via + * `loader.getHandler('model').addParser(new ObjModelParser(device))`, and + * `playcanvas/scripts/esm/parsers/spz-parser.mjs` adds `.spz` Gaussian-splat loading via + * `loader.getHandler('gsplat').addParser(new SpzParser(app))`. */ class ResourceLoader { /** diff --git a/src/framework/script/script.js b/src/framework/script/script.js index 799b774a85b..21384df3aba 100644 --- a/src/framework/script/script.js +++ b/src/framework/script/script.js @@ -43,6 +43,12 @@ import { SCRIPT_INITIALIZE, SCRIPT_POST_INITIALIZE } from './constants.js'; * * For more information on how to create scripts, see the [Scripting Overview](https://developer.playcanvas.com/user-manual/scripting/). * + * The `playcanvas` package also ships a library of ready-to-use `Script` subclasses under the + * `playcanvas/scripts/esm/` subpath — camera and character controllers, post-processing, water, + * sky, grid, shadow catcher, planar reflections, XR and Gaussian-splat effects. Import them + * directly, for example + * `import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs'`. + * * @category Script */ export class Script extends EventHandler { diff --git a/src/framework/xr/xr-manager.js b/src/framework/xr/xr-manager.js index 991f0c7e4cb..9864b66efc4 100644 --- a/src/framework/xr/xr-manager.js +++ b/src/framework/xr/xr-manager.js @@ -49,6 +49,12 @@ import { DEVICETYPE_WEBGPU } from '../../platform/graphics/constants.js'; * The {@link AppBase} class automatically creates an instance of this class and makes it available * as {@link AppBase#xr}. * + * Ready-made XR building blocks ship under `playcanvas/scripts/esm/xr/`: `xr-session.mjs` for + * session lifecycle and camera rig transforms, `xr-controllers.mjs` for WebXR controller and hand + * models, `xr-navigation.mjs` for teleportation, smooth locomotion and turning, + * `xr-manipulation.mjs` for two-handed drag, rotate and scale of the world, and `xr-menu.mjs` for + * hand-tracked and controller-driven 3D menus. + * * @category XR */ class XrManager extends EventHandler { diff --git a/src/platform/input/game-pads.js b/src/platform/input/game-pads.js index 109615b7119..cb4a8762a2e 100644 --- a/src/platform/input/game-pads.js +++ b/src/platform/input/game-pads.js @@ -766,6 +766,10 @@ class GamePad { /** * Input handler for accessing GamePad input. * + * For frame-accumulated input deltas rather than raw pad state, see {@link GamepadSource}, + * {@link KeyboardMouseSource} and {@link MultiTouchSource}, which feed {@link InputController}s + * such as {@link OrbitController}, {@link FlyController} and {@link FocusController}. + * * @category Input */ class GamePads extends EventHandler { diff --git a/src/platform/input/keyboard.js b/src/platform/input/keyboard.js index e1b301c10ec..9bdbcf173af 100644 --- a/src/platform/input/keyboard.js +++ b/src/platform/input/keyboard.js @@ -69,6 +69,11 @@ const _keyCodeToKeyIdentifier = { * * Your application's Keyboard instance is managed and accessible via {@link AppBase#keyboard}. * + * For pointer-lock-aware, frame-accumulated input deltas rather than raw events, see + * {@link KeyboardMouseSource}, {@link GamepadSource} and {@link MultiTouchSource}, which feed + * {@link InputController}s such as {@link OrbitController}, {@link FlyController} and + * {@link FocusController}. + * * @category Input */ class Keyboard extends EventHandler { diff --git a/src/platform/input/mouse.js b/src/platform/input/mouse.js index 9c6c141581a..bfc7c70882e 100644 --- a/src/platform/input/mouse.js +++ b/src/platform/input/mouse.js @@ -20,6 +20,11 @@ import { isMousePointerLocked, MouseEvent } from './mouse-event.js'; * * Your application's Mouse instance is managed and accessible via {@link AppBase#mouse}. * + * For pointer-lock-aware, frame-accumulated input deltas rather than raw events, see + * {@link KeyboardMouseSource}, {@link GamepadSource} and {@link MultiTouchSource}, which feed + * {@link InputController}s such as {@link OrbitController}, {@link FlyController} and + * {@link FocusController}. + * * @category Input */ class Mouse extends EventHandler { diff --git a/src/scene/scene.js b/src/scene/scene.js index e6178624674..fbdb8bfd645 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -458,7 +458,10 @@ class Scene extends EventHandler { } /** - * Sets the environment lighting atlas. + * Sets the environment lighting atlas, an octahedral atlas of prefiltered mip levels. To build + * one from an equirectangular or cubemap source, use `EnvLighting.generateLightingSource` + * followed by `EnvLighting.generateAtlas`; a raw HDR texture assigned here will not light the + * scene correctly. * * @type {Texture|null} */ @@ -635,6 +638,11 @@ class Scene extends EventHandler { /** * Sets the base cubemap texture used as the scene's skybox when skyboxMip is 0. Defaults to null. * + * For a sky that needs no cubemap asset, `playcanvas/scripts/esm/sky/procedural-sky.mjs` + * renders an analytic daylight sky and keeps a directional light aligned with the sun so + * direct lighting and shadows match. Related scene-dressing scripts ship alongside it: + * `water.mjs`, `grid.mjs`, `shadow-catcher.mjs` and `blurred-planar-reflection.mjs`. + * * @type {Texture|null} */ set skybox(value) { From 0c61d855ae209a8b550cbb723fd6029646fdad03 Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 10:40:27 +0100 Subject: [PATCH 04/10] docs: correct behaviour claims that did not match the source Five of the notes added earlier in this branch describe behaviour that the source does not have. Each was checked against the implementation: - CameraFrame: ssao is gated by its `type` and colorLUT by its `texture`, not by an `enabled` flag, so `ssao.enabled = true` silently does nothing. - CameraComponent#worldToScreen: `z` is unnormalized clip depth, so it is also negative for points nearer than twice the near clip and across the near half of an orthographic range. Point at the view space test that annotations.mjs already uses. - MiniStats: script, anim, physics and gsplat sort timings are measured in every build. Only the render timing needs _PROFILER, and without it the counter reports time since page load rather than zero. - Asset#ready: a callback registered after a failed load runs immediately with a null resource, because the error path still sets `loaded`. - GraphNode#lookAt: a degenerate basis resets the rotation to identity rather than leaving the existing rotation in place. --- scripts/esm/camera-frame.mjs | 6 ++++-- src/extras/mini-stats/mini-stats.js | 8 +++++--- src/framework/asset/asset.js | 8 +++++--- src/framework/components/camera/component.js | 8 ++++++-- src/scene/graph-node.js | 4 ++-- 5 files changed, 22 insertions(+), 12 deletions(-) diff --git a/scripts/esm/camera-frame.mjs b/scripts/esm/camera-frame.mjs index 08548f373fa..746f6bdecd5 100644 --- a/scripts/esm/camera-frame.mjs +++ b/scripts/esm/camera-frame.mjs @@ -633,8 +633,10 @@ class VolumetricFog { * of field and volumetric fog. * * Attach the script to an entity with a camera component and adjust the attribute groups to - * configure the post-processing stack. Every group except `rendering` is gated by its own - * `enabled` flag, which defaults to false. + * configure the post-processing stack. Most groups are gated by their own `enabled` flag, which + * defaults to false. Three are not: `rendering` is always applied, `ssao` is gated by its `type` + * (`SsaoType.NONE` by default) and `colorLUT` by its `texture` (null by default) — setting + * `enabled` on those two does nothing. * * Set the fields on the groups after creating the script. Do not pass a group through the * `properties` argument of {@link ScriptComponent#create}: that assignment is shallow, so it diff --git a/src/extras/mini-stats/mini-stats.js b/src/extras/mini-stats/mini-stats.js index aea5906efad..61f25768c01 100644 --- a/src/extras/mini-stats/mini-stats.js +++ b/src/extras/mini-stats/mini-stats.js @@ -77,9 +77,11 @@ const delayedStartStats = new Set([ * it shows CPU and GPU utilization, frame timings and draw call count. It can also be configured * to display additional graphs based on data collected into `AppBase#stats`. * - * Detailed per-frame sub-timings — render, script, anim and physics — are only populated in the - * profiler build; import from `'playcanvas/profiler'` to obtain them. In other builds those - * counters read zero. + * The detailed per-frame sub-timings — script, anim, physics and gsplat sort — are measured in + * every build. The render timing is the exception: its start timestamp is only recorded in the + * debug and profiler builds, so in the release build the render graph reports the time elapsed + * since page load rather than a frame time. Import from `'playcanvas/debug'` or + * `'playcanvas/profiler'` for a meaningful render figure. */ class MiniStats { /** diff --git a/src/framework/asset/asset.js b/src/framework/asset/asset.js index 6bc379fc96d..294e7817308 100644 --- a/src/framework/asset/asset.js +++ b/src/framework/asset/asset.js @@ -554,9 +554,11 @@ class Asset extends EventHandler { * Take a callback which is called as soon as the asset is loaded. If the asset is already * loaded the callback is called straight away. * - * The callback fires on success only. A failed load still marks the asset as loaded, but fires - * `error` rather than `load`, so this callback never runs — listen for the `error` event as - * well whenever a failure has to be handled, and never await this callback alone. + * The callback fires on success only, and a failed load still marks the asset as loaded while + * firing `error` rather than `load`. So a callback registered before the failure never runs, + * and one registered after it runs immediately with {@link Asset#resource} still null. Listen + * for the `error` event as well whenever a failure has to be handled, check `asset.resource` + * inside the callback, and never await this callback alone. * * @param {AssetReadyCallback} callback - The function called when the asset is ready. Passed * the (asset) arguments. diff --git a/src/framework/components/camera/component.js b/src/framework/components/camera/component.js index 75e29762039..aabe5af8bbe 100644 --- a/src/framework/components/camera/component.js +++ b/src/framework/components/camera/component.js @@ -1153,8 +1153,12 @@ class CameraComponent extends Component { /** * Convert a point from 3D world space to 2D screen space. * - * A returned `z` of zero or less means the point is behind the camera and the x and y values - * are not meaningful. For DOM labels anchored to world positions, + * The returned `z` is the unnormalized clip space depth, not a behind-the-camera flag: it also + * goes negative for points in front of a perspective camera that are nearer than twice the + * near clip, and for an orthographic camera it is negative across the whole near half of the + * depth range. To reject points behind the camera, test the view space depth instead - pass + * the world position through {@link CameraComponent#viewMatrix} and discard it when the + * resulting `z` is zero or greater. For DOM labels anchored to world positions, * `playcanvas/scripts/esm/annotations.mjs` provides `Annotation` and `AnnotationManager`, * which handle behind-camera rejection and occlusion fading. * diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 751d1d0313d..53e789fcbde 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -1601,8 +1601,8 @@ class GraphNode extends EventHandler { * * The up vector must not be parallel to the direction from the node to the target. When it is — * looking straight up or down with the default up vector, or at the node's own position — the - * basis is degenerate and the node is left unrotated, with nothing reported. Pass a different - * up vector in those cases. + * basis is degenerate and the node's rotation is reset to identity, discarding whatever + * rotation it already had, with nothing reported. Pass a different up vector in those cases. * * @overload * @param {number} x - X-component of the world space coordinate to look at. From a22091dfc1ab9a168189a043dce7eb0ee8377865 Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 10:40:44 +0100 Subject: [PATCH 05/10] docs: mark legacy members deprecated in the type declarations 62 legacy members warn at runtime via Debug.deprecated/Debug.removed but carry no doc block, so they reach build/playcanvas.d.ts as bare signatures such as `scale(scalar: any): Vec3;`. A model trained on the pre-2.x API has no authoring-time signal that the idiom is legacy, and the `any` parameter means the call typechecks clean. Each now carries a one-line block using the pattern already in GSplatComponent: `@deprecated @ignore`. The marker reaches the declarations while `@ignore` keeps the member out of the API reference exactly as an absent block did, and because no `@param`/`@returns` is supplied the inferred signature is untouched. `jsdoc/require-param` and `jsdoc/require-returns` fire as soon as a block exists, and supplying those tags would narrow published signatures, so both are exempted for `@deprecated` blocks in the repo config. Skipped: src/deprecated/ (already excluded wholesale), impl-level accessors (_glFrameBuffer, _glTexture) and engine internals no caller writes (setupCullMode, BatchManager#clone, EventHandle#on/once). Verified against main at 2e1fe0272: - public API surface via utils/api-surface.mjs: byte-identical, 5984 lines - .d.ts declaration tokens excluding comments: 0 differences - @deprecated in .d.ts: 53 -> 115 - typedoc: 0 errors, warnings unchanged at 34 - npm run lint clean; npm test 2210 passing; npm run test:types passes --- eslint.config.mjs | 7 ++++++- src/core/math/vec2.js | 1 + src/core/math/vec3.js | 1 + src/core/math/vec4.js | 1 + src/platform/graphics/blend-state.js | 1 + src/platform/graphics/graphics-device.js | 22 ++++++++++++++++++++++ src/platform/graphics/render-target.js | 1 + src/platform/graphics/texture.js | 4 ++++ src/platform/graphics/vertex-format.js | 1 + src/scene/graph-node.js | 6 ++++++ src/scene/materials/material.js | 2 ++ src/scene/morph.js | 1 + src/scene/scene.js | 21 +++++++++++++++++++++ 13 files changed, 68 insertions(+), 1 deletion(-) diff --git a/eslint.config.mjs b/eslint.config.mjs index db30dea15f5..80d358983af 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -31,7 +31,12 @@ export default [ // extra tags, which this override would otherwise drop by replacing the rule definedTags: [...new Set([...esmScriptTags, 'alpha', 'beta', 'category', 'import'])] } - ] + ], + // a deprecated member is documented only to carry the @deprecated marker into the type + // declarations - requiring @param/@returns there would publish types for API we are + // steering callers away from, so exempt those blocks + 'jsdoc/require-param': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }], + 'jsdoc/require-returns': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }] } }, { diff --git a/src/core/math/vec2.js b/src/core/math/vec2.js index c356ba5a440..dd1596af43d 100644 --- a/src/core/math/vec2.js +++ b/src/core/math/vec2.js @@ -438,6 +438,7 @@ class Vec2 { return this; } + /** @deprecated Vec2#scale is deprecated. Use Vec2#mulScalar instead. @ignore */ scale(scalar) { Debug.deprecated('Vec2#scale is deprecated. Use Vec2#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/core/math/vec3.js b/src/core/math/vec3.js index 74db3abf1db..e965a2de137 100644 --- a/src/core/math/vec3.js +++ b/src/core/math/vec3.js @@ -473,6 +473,7 @@ class Vec3 { return this; } + /** @deprecated Vec3#scale is deprecated. Use Vec3#mulScalar instead. @ignore */ scale(scalar) { Debug.deprecated('Vec3#scale is deprecated. Use Vec3#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/core/math/vec4.js b/src/core/math/vec4.js index 1a12faebc5b..5c449005316 100644 --- a/src/core/math/vec4.js +++ b/src/core/math/vec4.js @@ -450,6 +450,7 @@ class Vec4 { return this; } + /** @deprecated Vec4#scale is deprecated. Use Vec4#mulScalar instead. @ignore */ scale(scalar) { Debug.deprecated('Vec4#scale is deprecated. Use Vec4#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/platform/graphics/blend-state.js b/src/platform/graphics/blend-state.js index 1347f0612ef..2872265e068 100644 --- a/src/platform/graphics/blend-state.js +++ b/src/platform/graphics/blend-state.js @@ -462,6 +462,7 @@ class BlendState { */ static NOBLEND = Object.freeze(new BlendState()); + /** @deprecated BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead. @ignore */ static get DEFAULT() { Debug.deprecated('BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead.'); return BlendState.NOBLEND; diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index 9648f89da46..b410ab3f930 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -928,71 +928,85 @@ class GraphicsDevice extends EventHandler { // ---- deprecated block start ---- + /** @deprecated GraphicsDevice#boneLimit is deprecated and the limit has been removed. @ignore */ get boneLimit() { Debug.deprecated('GraphicsDevice#boneLimit is deprecated and the limit has been removed.'); return 1024; } + /** @deprecated GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead. @ignore */ get webgl2() { Debug.deprecated('GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead.'); return this.isWebGL2; } + /** @deprecated GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true. @ignore */ get textureFloatHighPrecision() { Debug.deprecated('GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true.'); return true; } + /** @deprecated GraphicsDevice#extBlendMinmax is deprecated as it is always true. @ignore */ get extBlendMinmax() { Debug.deprecated('GraphicsDevice#extBlendMinmax is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#extTextureHalfFloat is deprecated as it is always true. @ignore */ get extTextureHalfFloat() { Debug.deprecated('GraphicsDevice#extTextureHalfFloat is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#extTextureLod is deprecated as it is always true. @ignore */ get extTextureLod() { Debug.deprecated('GraphicsDevice#extTextureLod is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true. @ignore */ get textureHalfFloatFilterable() { Debug.deprecated('GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#supportsMrt is deprecated as it is always true. @ignore */ get supportsMrt() { Debug.deprecated('GraphicsDevice#supportsMrt is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#supportsVolumeTextures is deprecated as it is always true. @ignore */ get supportsVolumeTextures() { Debug.deprecated('GraphicsDevice#supportsVolumeTextures is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#supportsInstancing is deprecated as it is always true. @ignore */ get supportsInstancing() { Debug.deprecated('GraphicsDevice#supportsInstancing is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true. @ignore */ get textureHalfFloatUpdatable() { Debug.deprecated('GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#extTextureFloat is deprecated as it is always true @ignore */ get extTextureFloat() { Debug.deprecated('GraphicsDevice#extTextureFloat is deprecated as it is always true'); return true; } + /** @deprecated GraphicsDevice#extStandardDerivatives is deprecated as it is always true. @ignore */ get extStandardDerivatives() { Debug.deprecated('GraphicsDevice#extStandardDerivatives is deprecated as it is always true.'); return true; } + /** @deprecated GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setBlendFunction(blendSrc, blendDst) { Debug.deprecated('GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1002,6 +1016,7 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } + /** @deprecated GraphicsDevice#setBlendFunctionSeparate is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha) { Debug.deprecated('GraphicsDevice#setBlendFunctionSeparate is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1011,6 +1026,7 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } + /** @deprecated GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setBlendEquation(blendEquation) { Debug.deprecated('GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1020,6 +1036,7 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } + /** @deprecated GraphicsDevice#setBlendEquationSeparate is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setBlendEquationSeparate(blendEquation, blendAlphaEquation) { Debug.deprecated('GraphicsDevice#setBlendEquationSeparate is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1029,6 +1046,7 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } + /** @deprecated GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setColorWrite(redWrite, greenWrite, blueWrite, alphaWrite) { Debug.deprecated('GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1041,6 +1059,7 @@ class GraphicsDevice extends EventHandler { return this.blendState.blend; } + /** @deprecated GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ setBlending(blending) { Debug.deprecated('GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState instead.'); _tempBlendState.copy(this.blendState); @@ -1048,6 +1067,7 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } + /** @deprecated GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ setDepthWrite(write) { Debug.deprecated('GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); @@ -1055,6 +1075,7 @@ class GraphicsDevice extends EventHandler { this.setDepthState(_tempDepthState); } + /** @deprecated GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ setDepthFunc(func) { Debug.deprecated('GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); @@ -1062,6 +1083,7 @@ class GraphicsDevice extends EventHandler { this.setDepthState(_tempDepthState); } + /** @deprecated GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ setDepthTest(test) { Debug.deprecated('GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); diff --git a/src/platform/graphics/render-target.js b/src/platform/graphics/render-target.js index 1405b003032..0b4c69caf89 100644 --- a/src/platform/graphics/render-target.js +++ b/src/platform/graphics/render-target.js @@ -573,6 +573,7 @@ class RenderTarget { return success; } + /** @deprecated RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM. @ignore */ set flipY(value) { Debug.deprecated('RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM.'); this._flipY = value; diff --git a/src/platform/graphics/texture.js b/src/platform/graphics/texture.js index e7a41540593..94197f9d420 100644 --- a/src/platform/graphics/texture.js +++ b/src/platform/graphics/texture.js @@ -953,21 +953,25 @@ class Texture { return this._type; } + /** @deprecated Texture#rgbm is deprecated. Use Texture#type instead. @ignore */ set rgbm(value) { Debug.deprecated('Texture#rgbm is deprecated. Use Texture#type instead.'); this.type = value ? TEXTURETYPE_RGBM : TEXTURETYPE_DEFAULT; } + /** @deprecated Texture#rgbm is deprecated. Use Texture#type instead. @ignore */ get rgbm() { Debug.deprecated('Texture#rgbm is deprecated. Use Texture#type instead.'); return this.type === TEXTURETYPE_RGBM; } + /** @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. @ignore */ set swizzleGGGR(value) { Debug.deprecated('Texture#swizzleGGGR is deprecated. Use Texture#type instead.'); this.type = value ? TEXTURETYPE_SWIZZLEGGGR : TEXTURETYPE_DEFAULT; } + /** @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. @ignore */ get swizzleGGGR() { Debug.deprecated('Texture#swizzleGGGR is deprecated. Use Texture#type instead.'); return this.type === TEXTURETYPE_SWIZZLEGGGR; diff --git a/src/platform/graphics/vertex-format.js b/src/platform/graphics/vertex-format.js index 909244b32b7..05de8b7d361 100644 --- a/src/platform/graphics/vertex-format.js +++ b/src/platform/graphics/vertex-format.js @@ -236,6 +236,7 @@ class VertexFormat { }); } + /** @deprecated VertexFormat.defaultInstancingFormat was removed. Use VertexFormat.getDefaultInstancingFormat(graphicsDevice). @ignore */ static get defaultInstancingFormat() { Debug.removed('VertexFormat.defaultInstancingFormat was removed. Use VertexFormat.getDefaultInstancingFormat(graphicsDevice).'); return null; diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 53e789fcbde..3a2b3d7a702 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -398,31 +398,37 @@ class GraphNode extends EventHandler { // ---- deprecated block start ---- + /** @deprecated GraphNode#getChildren is deprecated. Use GraphNode#children instead. @ignore */ getChildren() { Debug.deprecated('GraphNode#getChildren is deprecated. Use GraphNode#children instead.'); return this.children; } + /** @deprecated GraphNode#getName is deprecated. Use GraphNode#name instead. @ignore */ getName() { Debug.deprecated('GraphNode#getName is deprecated. Use GraphNode#name instead.'); return this.name; } + /** @deprecated GraphNode#getPath is deprecated. Use GraphNode#path instead. @ignore */ getPath() { Debug.deprecated('GraphNode#getPath is deprecated. Use GraphNode#path instead.'); return this.path; } + /** @deprecated GraphNode#getRoot is deprecated. Use GraphNode#root instead. @ignore */ getRoot() { Debug.deprecated('GraphNode#getRoot is deprecated. Use GraphNode#root instead.'); return this.root; } + /** @deprecated GraphNode#getParent is deprecated. Use GraphNode#parent instead. @ignore */ getParent() { Debug.deprecated('GraphNode#getParent is deprecated. Use GraphNode#parent instead.'); return this.parent; } + /** @deprecated GraphNode#setName is deprecated. Use GraphNode#name instead. @ignore */ setName(name) { Debug.deprecated('GraphNode#setName is deprecated. Use GraphNode#name instead.'); this.name = name; diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index bc07330ac7d..3dba33ec82f 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -307,11 +307,13 @@ class Material { return this.shaderChunks.version; } + /** @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") @ignore */ set chunks(value) { Debug.deprecated('Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode")'); this._oldChunks = value; } + /** @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") @ignore */ get chunks() { Debug.deprecated('Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode")'); Object.assign(this._oldChunks, Object.fromEntries(this.shaderChunks.glsl)); diff --git a/src/scene/morph.js b/src/scene/morph.js index a5b3fbb7b6a..a34be0f7757 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -263,6 +263,7 @@ class Morph extends RefCountedObject { // ---- deprecated block start ---- + /** @deprecated Morph#getTarget is deprecated. Use Morph#targets instead. @ignore */ getTarget(index) { Debug.deprecated('Morph#getTarget is deprecated. Use Morph#targets instead.'); return this.targets[index]; diff --git a/src/scene/scene.js b/src/scene/scene.js index fbdb8bfd645..6d8d8cebc02 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -923,112 +923,133 @@ class Scene extends EventHandler { // ---- deprecated block start ---- + /** @deprecated Scene#defaultMaterial is deprecated. @ignore */ get defaultMaterial() { Debug.deprecated('Scene#defaultMaterial is deprecated.'); return getDefaultMaterial(this.device); } + /** @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. @ignore */ set fogColor(value) { Debug.deprecated('Scene#fogColor is deprecated. Use Scene#fog.color instead.'); this.fog.color = value; } + /** @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. @ignore */ get fogColor() { Debug.deprecated('Scene#fogColor is deprecated. Use Scene#fog.color instead.'); return this.fog.color; } + /** @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. @ignore */ set fogEnd(value) { Debug.deprecated('Scene#fogEnd is deprecated. Use Scene#fog.end instead.'); this.fog.end = value; } + /** @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. @ignore */ get fogEnd() { Debug.deprecated('Scene#fogEnd is deprecated. Use Scene#fog.end instead.'); return this.fog.end; } + /** @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. @ignore */ set fogStart(value) { Debug.deprecated('Scene#fogStart is deprecated. Use Scene#fog.start instead.'); this.fog.start = value; } + /** @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. @ignore */ get fogStart() { Debug.deprecated('Scene#fogStart is deprecated. Use Scene#fog.start instead.'); return this.fog.start; } + /** @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. @ignore */ set fogDensity(value) { Debug.deprecated('Scene#fogDensity is deprecated. Use Scene#fog.density instead.'); this.fog.density = value; } + /** @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. @ignore */ get fogDensity() { Debug.deprecated('Scene#fogDensity is deprecated. Use Scene#fog.density instead.'); return this.fog.density; } + /** @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered128(value) { Debug.deprecated('Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[0] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered128() { Debug.deprecated('Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[0]; } + /** @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered64(value) { Debug.deprecated('Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[1] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered64() { Debug.deprecated('Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[1]; } + /** @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered32(value) { Debug.deprecated('Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[2] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered32() { Debug.deprecated('Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[2]; } + /** @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered16(value) { Debug.deprecated('Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[3] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered16() { Debug.deprecated('Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[3]; } + /** @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered8(value) { Debug.deprecated('Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[4] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered8() { Debug.deprecated('Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[4]; } + /** @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ set skyboxPrefiltered4(value) { Debug.deprecated('Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[5] = value; this.updateShaders = true; } + /** @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ get skyboxPrefiltered4() { Debug.deprecated('Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[5]; From 601efd2ed9881e774938d726f983a847ba92cd53 Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 10:52:33 +0100 Subject: [PATCH 06/10] docs: expand the deprecation markers to multi-line JSDoc blocks The markers added in 2b9f49c4a used a single-line block. Multi-line is the JSDoc convention in this repo, so each of the 62 is expanded, with the tag description wrapped at the 100 column width the surrounding blocks use. Re-verified against main at 2e1fe0272: public API surface byte-identical at 5984 lines, .d.ts declaration tokens unchanged, @deprecated at 115, lint clean, 2210 tests passing. --- src/core/math/vec2.js | 5 +- src/core/math/vec3.js | 5 +- src/core/math/vec4.js | 5 +- src/platform/graphics/blend-state.js | 5 +- src/platform/graphics/graphics-device.js | 119 ++++++++++++++++++----- src/platform/graphics/render-target.js | 7 +- src/platform/graphics/texture.js | 20 +++- src/platform/graphics/vertex-format.js | 6 +- src/scene/graph-node.js | 30 ++++-- src/scene/materials/material.js | 12 ++- src/scene/morph.js | 5 +- src/scene/scene.js | 105 ++++++++++++++++---- 12 files changed, 262 insertions(+), 62 deletions(-) diff --git a/src/core/math/vec2.js b/src/core/math/vec2.js index dd1596af43d..a4b04c7ce1f 100644 --- a/src/core/math/vec2.js +++ b/src/core/math/vec2.js @@ -438,7 +438,10 @@ class Vec2 { return this; } - /** @deprecated Vec2#scale is deprecated. Use Vec2#mulScalar instead. @ignore */ + /** + * @deprecated Vec2#scale is deprecated. Use Vec2#mulScalar instead. + * @ignore + */ scale(scalar) { Debug.deprecated('Vec2#scale is deprecated. Use Vec2#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/core/math/vec3.js b/src/core/math/vec3.js index e965a2de137..4876f6d95e6 100644 --- a/src/core/math/vec3.js +++ b/src/core/math/vec3.js @@ -473,7 +473,10 @@ class Vec3 { return this; } - /** @deprecated Vec3#scale is deprecated. Use Vec3#mulScalar instead. @ignore */ + /** + * @deprecated Vec3#scale is deprecated. Use Vec3#mulScalar instead. + * @ignore + */ scale(scalar) { Debug.deprecated('Vec3#scale is deprecated. Use Vec3#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/core/math/vec4.js b/src/core/math/vec4.js index 5c449005316..044481d2f0f 100644 --- a/src/core/math/vec4.js +++ b/src/core/math/vec4.js @@ -450,7 +450,10 @@ class Vec4 { return this; } - /** @deprecated Vec4#scale is deprecated. Use Vec4#mulScalar instead. @ignore */ + /** + * @deprecated Vec4#scale is deprecated. Use Vec4#mulScalar instead. + * @ignore + */ scale(scalar) { Debug.deprecated('Vec4#scale is deprecated. Use Vec4#mulScalar instead.'); return this.mulScalar(scalar); diff --git a/src/platform/graphics/blend-state.js b/src/platform/graphics/blend-state.js index 2872265e068..3c57b751cc4 100644 --- a/src/platform/graphics/blend-state.js +++ b/src/platform/graphics/blend-state.js @@ -462,7 +462,10 @@ class BlendState { */ static NOBLEND = Object.freeze(new BlendState()); - /** @deprecated BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead. @ignore */ + /** + * @deprecated BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead. + * @ignore + */ static get DEFAULT() { Debug.deprecated('BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead.'); return BlendState.NOBLEND; diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index b410ab3f930..ee52542268b 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -928,85 +928,128 @@ class GraphicsDevice extends EventHandler { // ---- deprecated block start ---- - /** @deprecated GraphicsDevice#boneLimit is deprecated and the limit has been removed. @ignore */ + /** + * @deprecated GraphicsDevice#boneLimit is deprecated and the limit has been removed. + * @ignore + */ get boneLimit() { Debug.deprecated('GraphicsDevice#boneLimit is deprecated and the limit has been removed.'); return 1024; } - /** @deprecated GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead. @ignore */ + /** + * @deprecated GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead. + * @ignore + */ get webgl2() { Debug.deprecated('GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead.'); return this.isWebGL2; } - /** @deprecated GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true. @ignore */ + /** + * @deprecated GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true. + * @ignore + */ get textureFloatHighPrecision() { Debug.deprecated('GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true.'); return true; } - /** @deprecated GraphicsDevice#extBlendMinmax is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#extBlendMinmax is deprecated as it is always true. + * @ignore + */ get extBlendMinmax() { Debug.deprecated('GraphicsDevice#extBlendMinmax is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#extTextureHalfFloat is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#extTextureHalfFloat is deprecated as it is always true. + * @ignore + */ get extTextureHalfFloat() { Debug.deprecated('GraphicsDevice#extTextureHalfFloat is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#extTextureLod is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#extTextureLod is deprecated as it is always true. + * @ignore + */ get extTextureLod() { Debug.deprecated('GraphicsDevice#extTextureLod is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true. + * @ignore + */ get textureHalfFloatFilterable() { Debug.deprecated('GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#supportsMrt is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#supportsMrt is deprecated as it is always true. + * @ignore + */ get supportsMrt() { Debug.deprecated('GraphicsDevice#supportsMrt is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#supportsVolumeTextures is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#supportsVolumeTextures is deprecated as it is always true. + * @ignore + */ get supportsVolumeTextures() { Debug.deprecated('GraphicsDevice#supportsVolumeTextures is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#supportsInstancing is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#supportsInstancing is deprecated as it is always true. + * @ignore + */ get supportsInstancing() { Debug.deprecated('GraphicsDevice#supportsInstancing is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true. + * @ignore + */ get textureHalfFloatUpdatable() { Debug.deprecated('GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#extTextureFloat is deprecated as it is always true @ignore */ + /** + * @deprecated GraphicsDevice#extTextureFloat is deprecated as it is always true + * @ignore + */ get extTextureFloat() { Debug.deprecated('GraphicsDevice#extTextureFloat is deprecated as it is always true'); return true; } - /** @deprecated GraphicsDevice#extStandardDerivatives is deprecated as it is always true. @ignore */ + /** + * @deprecated GraphicsDevice#extStandardDerivatives is deprecated as it is always true. + * @ignore + */ get extStandardDerivatives() { Debug.deprecated('GraphicsDevice#extStandardDerivatives is deprecated as it is always true.'); return true; } - /** @deprecated GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState + * instead. + * @ignore + */ setBlendFunction(blendSrc, blendDst) { Debug.deprecated('GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1016,7 +1059,11 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } - /** @deprecated GraphicsDevice#setBlendFunctionSeparate is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setBlendFunctionSeparate is deprecated, use + * GraphicsDevice.setBlendState instead. + * @ignore + */ setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha) { Debug.deprecated('GraphicsDevice#setBlendFunctionSeparate is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1026,7 +1073,11 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } - /** @deprecated GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState + * instead. + * @ignore + */ setBlendEquation(blendEquation) { Debug.deprecated('GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1036,7 +1087,11 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } - /** @deprecated GraphicsDevice#setBlendEquationSeparate is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setBlendEquationSeparate is deprecated, use + * GraphicsDevice.setBlendState instead. + * @ignore + */ setBlendEquationSeparate(blendEquation, blendAlphaEquation) { Debug.deprecated('GraphicsDevice#setBlendEquationSeparate is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1046,7 +1101,11 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } - /** @deprecated GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState + * instead. + * @ignore + */ setColorWrite(redWrite, greenWrite, blueWrite, alphaWrite) { Debug.deprecated('GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState instead.'); const currentBlendState = this.blendState; @@ -1059,7 +1118,11 @@ class GraphicsDevice extends EventHandler { return this.blendState.blend; } - /** @deprecated GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState + * instead. + * @ignore + */ setBlending(blending) { Debug.deprecated('GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState instead.'); _tempBlendState.copy(this.blendState); @@ -1067,7 +1130,11 @@ class GraphicsDevice extends EventHandler { this.setBlendState(_tempBlendState); } - /** @deprecated GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState + * instead. + * @ignore + */ setDepthWrite(write) { Debug.deprecated('GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); @@ -1075,7 +1142,11 @@ class GraphicsDevice extends EventHandler { this.setDepthState(_tempDepthState); } - /** @deprecated GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState + * instead. + * @ignore + */ setDepthFunc(func) { Debug.deprecated('GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); @@ -1083,7 +1154,11 @@ class GraphicsDevice extends EventHandler { this.setDepthState(_tempDepthState); } - /** @deprecated GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState instead. @ignore */ + /** + * @deprecated GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState + * instead. + * @ignore + */ setDepthTest(test) { Debug.deprecated('GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState instead.'); _tempDepthState.copy(this.depthState); diff --git a/src/platform/graphics/render-target.js b/src/platform/graphics/render-target.js index 0b4c69caf89..0e73a7ea3b2 100644 --- a/src/platform/graphics/render-target.js +++ b/src/platform/graphics/render-target.js @@ -573,7 +573,12 @@ class RenderTarget { return success; } - /** @deprecated RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM. @ignore */ + /** + * @deprecated RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget + * constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: + * RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM. + * @ignore + */ set flipY(value) { Debug.deprecated('RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM.'); this._flipY = value; diff --git a/src/platform/graphics/texture.js b/src/platform/graphics/texture.js index 94197f9d420..dad3c454fb7 100644 --- a/src/platform/graphics/texture.js +++ b/src/platform/graphics/texture.js @@ -953,25 +953,37 @@ class Texture { return this._type; } - /** @deprecated Texture#rgbm is deprecated. Use Texture#type instead. @ignore */ + /** + * @deprecated Texture#rgbm is deprecated. Use Texture#type instead. + * @ignore + */ set rgbm(value) { Debug.deprecated('Texture#rgbm is deprecated. Use Texture#type instead.'); this.type = value ? TEXTURETYPE_RGBM : TEXTURETYPE_DEFAULT; } - /** @deprecated Texture#rgbm is deprecated. Use Texture#type instead. @ignore */ + /** + * @deprecated Texture#rgbm is deprecated. Use Texture#type instead. + * @ignore + */ get rgbm() { Debug.deprecated('Texture#rgbm is deprecated. Use Texture#type instead.'); return this.type === TEXTURETYPE_RGBM; } - /** @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. @ignore */ + /** + * @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. + * @ignore + */ set swizzleGGGR(value) { Debug.deprecated('Texture#swizzleGGGR is deprecated. Use Texture#type instead.'); this.type = value ? TEXTURETYPE_SWIZZLEGGGR : TEXTURETYPE_DEFAULT; } - /** @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. @ignore */ + /** + * @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. + * @ignore + */ get swizzleGGGR() { Debug.deprecated('Texture#swizzleGGGR is deprecated. Use Texture#type instead.'); return this.type === TEXTURETYPE_SWIZZLEGGGR; diff --git a/src/platform/graphics/vertex-format.js b/src/platform/graphics/vertex-format.js index 05de8b7d361..3dcfb969556 100644 --- a/src/platform/graphics/vertex-format.js +++ b/src/platform/graphics/vertex-format.js @@ -236,7 +236,11 @@ class VertexFormat { }); } - /** @deprecated VertexFormat.defaultInstancingFormat was removed. Use VertexFormat.getDefaultInstancingFormat(graphicsDevice). @ignore */ + /** + * @deprecated VertexFormat.defaultInstancingFormat was removed. Use + * VertexFormat.getDefaultInstancingFormat(graphicsDevice). + * @ignore + */ static get defaultInstancingFormat() { Debug.removed('VertexFormat.defaultInstancingFormat was removed. Use VertexFormat.getDefaultInstancingFormat(graphicsDevice).'); return null; diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 3a2b3d7a702..864cb57c1e3 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -398,37 +398,55 @@ class GraphNode extends EventHandler { // ---- deprecated block start ---- - /** @deprecated GraphNode#getChildren is deprecated. Use GraphNode#children instead. @ignore */ + /** + * @deprecated GraphNode#getChildren is deprecated. Use GraphNode#children instead. + * @ignore + */ getChildren() { Debug.deprecated('GraphNode#getChildren is deprecated. Use GraphNode#children instead.'); return this.children; } - /** @deprecated GraphNode#getName is deprecated. Use GraphNode#name instead. @ignore */ + /** + * @deprecated GraphNode#getName is deprecated. Use GraphNode#name instead. + * @ignore + */ getName() { Debug.deprecated('GraphNode#getName is deprecated. Use GraphNode#name instead.'); return this.name; } - /** @deprecated GraphNode#getPath is deprecated. Use GraphNode#path instead. @ignore */ + /** + * @deprecated GraphNode#getPath is deprecated. Use GraphNode#path instead. + * @ignore + */ getPath() { Debug.deprecated('GraphNode#getPath is deprecated. Use GraphNode#path instead.'); return this.path; } - /** @deprecated GraphNode#getRoot is deprecated. Use GraphNode#root instead. @ignore */ + /** + * @deprecated GraphNode#getRoot is deprecated. Use GraphNode#root instead. + * @ignore + */ getRoot() { Debug.deprecated('GraphNode#getRoot is deprecated. Use GraphNode#root instead.'); return this.root; } - /** @deprecated GraphNode#getParent is deprecated. Use GraphNode#parent instead. @ignore */ + /** + * @deprecated GraphNode#getParent is deprecated. Use GraphNode#parent instead. + * @ignore + */ getParent() { Debug.deprecated('GraphNode#getParent is deprecated. Use GraphNode#parent instead.'); return this.parent; } - /** @deprecated GraphNode#setName is deprecated. Use GraphNode#name instead. @ignore */ + /** + * @deprecated GraphNode#setName is deprecated. Use GraphNode#name instead. + * @ignore + */ setName(name) { Debug.deprecated('GraphNode#setName is deprecated. Use GraphNode#name instead.'); this.name = name; diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index 3dba33ec82f..7961d18ae5d 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -307,13 +307,21 @@ class Material { return this.shaderChunks.version; } - /** @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") @ignore */ + /** + * @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. + * For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @ignore + */ set chunks(value) { Debug.deprecated('Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode")'); this._oldChunks = value; } - /** @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") @ignore */ + /** + * @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. + * For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @ignore + */ get chunks() { Debug.deprecated('Material.chunks has been removed, please use Material.getShaderChunks instead. For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode")'); Object.assign(this._oldChunks, Object.fromEntries(this.shaderChunks.glsl)); diff --git a/src/scene/morph.js b/src/scene/morph.js index a34be0f7757..7aa5ac23005 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -263,7 +263,10 @@ class Morph extends RefCountedObject { // ---- deprecated block start ---- - /** @deprecated Morph#getTarget is deprecated. Use Morph#targets instead. @ignore */ + /** + * @deprecated Morph#getTarget is deprecated. Use Morph#targets instead. + * @ignore + */ getTarget(index) { Debug.deprecated('Morph#getTarget is deprecated. Use Morph#targets instead.'); return this.targets[index]; diff --git a/src/scene/scene.js b/src/scene/scene.js index 6d8d8cebc02..61af20c871c 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -923,133 +923,196 @@ class Scene extends EventHandler { // ---- deprecated block start ---- - /** @deprecated Scene#defaultMaterial is deprecated. @ignore */ + /** + * @deprecated Scene#defaultMaterial is deprecated. + * @ignore + */ get defaultMaterial() { Debug.deprecated('Scene#defaultMaterial is deprecated.'); return getDefaultMaterial(this.device); } - /** @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. @ignore */ + /** + * @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. + * @ignore + */ set fogColor(value) { Debug.deprecated('Scene#fogColor is deprecated. Use Scene#fog.color instead.'); this.fog.color = value; } - /** @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. @ignore */ + /** + * @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. + * @ignore + */ get fogColor() { Debug.deprecated('Scene#fogColor is deprecated. Use Scene#fog.color instead.'); return this.fog.color; } - /** @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. @ignore */ + /** + * @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. + * @ignore + */ set fogEnd(value) { Debug.deprecated('Scene#fogEnd is deprecated. Use Scene#fog.end instead.'); this.fog.end = value; } - /** @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. @ignore */ + /** + * @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. + * @ignore + */ get fogEnd() { Debug.deprecated('Scene#fogEnd is deprecated. Use Scene#fog.end instead.'); return this.fog.end; } - /** @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. @ignore */ + /** + * @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. + * @ignore + */ set fogStart(value) { Debug.deprecated('Scene#fogStart is deprecated. Use Scene#fog.start instead.'); this.fog.start = value; } - /** @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. @ignore */ + /** + * @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. + * @ignore + */ get fogStart() { Debug.deprecated('Scene#fogStart is deprecated. Use Scene#fog.start instead.'); return this.fog.start; } - /** @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. @ignore */ + /** + * @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. + * @ignore + */ set fogDensity(value) { Debug.deprecated('Scene#fogDensity is deprecated. Use Scene#fog.density instead.'); this.fog.density = value; } - /** @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. @ignore */ + /** + * @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. + * @ignore + */ get fogDensity() { Debug.deprecated('Scene#fogDensity is deprecated. Use Scene#fog.density instead.'); return this.fog.density; } - /** @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered128(value) { Debug.deprecated('Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[0] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered128() { Debug.deprecated('Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[0]; } - /** @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered64(value) { Debug.deprecated('Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[1] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered64() { Debug.deprecated('Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[1]; } - /** @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered32(value) { Debug.deprecated('Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[2] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered32() { Debug.deprecated('Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[2]; } - /** @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered16(value) { Debug.deprecated('Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[3] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered16() { Debug.deprecated('Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[3]; } - /** @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered8(value) { Debug.deprecated('Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[4] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered8() { Debug.deprecated('Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[4]; } - /** @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ set skyboxPrefiltered4(value) { Debug.deprecated('Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead.'); this._prefilteredCubemaps[5] = value; this.updateShaders = true; } - /** @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. @ignore */ + /** + * @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. + * @ignore + */ get skyboxPrefiltered4() { Debug.deprecated('Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead.'); return this._prefilteredCubemaps[5]; From fae5d0985bb9337fa2a485ca5a2a0ced70c89df7 Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 11:05:01 +0100 Subject: [PATCH 07/10] docs: drop the restated message from the deprecation markers The marker text was the Debug.deprecated message word for word, so each block repeated the member's own name and the phrase "is deprecated" that the tag already conveys, immediately above a call carrying the same sentence. The blocks now hold only what the tag cannot imply - the migration instruction - so `@deprecated Vec3#scale is deprecated. Use Vec3#mulScalar instead.` becomes `@deprecated Use Vec3#mulScalar instead.`. The runtime call keeps its full message, since a console line has to name the member it came from. Re-verified: public API surface byte-identical at 5984 lines, .d.ts declaration tokens unchanged, @deprecated at 115, lint clean, 2210 tests passing. --- src/core/math/vec2.js | 2 +- src/core/math/vec3.js | 2 +- src/core/math/vec4.js | 2 +- src/platform/graphics/blend-state.js | 2 +- src/platform/graphics/graphics-device.js | 53 ++++++++++-------------- src/platform/graphics/render-target.js | 6 +-- src/platform/graphics/texture.js | 8 ++-- src/platform/graphics/vertex-format.js | 3 +- src/scene/graph-node.js | 12 +++--- src/scene/materials/material.js | 8 ++-- src/scene/morph.js | 2 +- src/scene/scene.js | 42 +++++++++---------- 12 files changed, 66 insertions(+), 76 deletions(-) diff --git a/src/core/math/vec2.js b/src/core/math/vec2.js index a4b04c7ce1f..805afd0c3fb 100644 --- a/src/core/math/vec2.js +++ b/src/core/math/vec2.js @@ -439,7 +439,7 @@ class Vec2 { } /** - * @deprecated Vec2#scale is deprecated. Use Vec2#mulScalar instead. + * @deprecated Use Vec2#mulScalar instead. * @ignore */ scale(scalar) { diff --git a/src/core/math/vec3.js b/src/core/math/vec3.js index 4876f6d95e6..197ca2eb031 100644 --- a/src/core/math/vec3.js +++ b/src/core/math/vec3.js @@ -474,7 +474,7 @@ class Vec3 { } /** - * @deprecated Vec3#scale is deprecated. Use Vec3#mulScalar instead. + * @deprecated Use Vec3#mulScalar instead. * @ignore */ scale(scalar) { diff --git a/src/core/math/vec4.js b/src/core/math/vec4.js index 044481d2f0f..2256c6444a0 100644 --- a/src/core/math/vec4.js +++ b/src/core/math/vec4.js @@ -451,7 +451,7 @@ class Vec4 { } /** - * @deprecated Vec4#scale is deprecated. Use Vec4#mulScalar instead. + * @deprecated Use Vec4#mulScalar instead. * @ignore */ scale(scalar) { diff --git a/src/platform/graphics/blend-state.js b/src/platform/graphics/blend-state.js index 3c57b751cc4..ff5b713ab9d 100644 --- a/src/platform/graphics/blend-state.js +++ b/src/platform/graphics/blend-state.js @@ -463,7 +463,7 @@ class BlendState { static NOBLEND = Object.freeze(new BlendState()); /** - * @deprecated BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead. + * @deprecated Use BlendState.NOBLEND instead. * @ignore */ static get DEFAULT() { diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index ee52542268b..409ad237189 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -929,7 +929,7 @@ class GraphicsDevice extends EventHandler { // ---- deprecated block start ---- /** - * @deprecated GraphicsDevice#boneLimit is deprecated and the limit has been removed. + * @deprecated The limit has been removed. * @ignore */ get boneLimit() { @@ -938,7 +938,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#webgl2 is deprecated, use GraphicsDevice#isWebGL2 instead. + * @deprecated Use GraphicsDevice#isWebGL2 instead. * @ignore */ get webgl2() { @@ -947,7 +947,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#textureFloatHighPrecision is deprecated and always returns true. + * @deprecated Always returns true. * @ignore */ get textureFloatHighPrecision() { @@ -956,7 +956,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#extBlendMinmax is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get extBlendMinmax() { @@ -965,7 +965,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#extTextureHalfFloat is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get extTextureHalfFloat() { @@ -974,7 +974,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#extTextureLod is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get extTextureLod() { @@ -983,7 +983,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#textureHalfFloatFilterable is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get textureHalfFloatFilterable() { @@ -992,7 +992,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#supportsMrt is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get supportsMrt() { @@ -1001,7 +1001,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#supportsVolumeTextures is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get supportsVolumeTextures() { @@ -1010,7 +1010,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#supportsInstancing is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get supportsInstancing() { @@ -1019,7 +1019,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#textureHalfFloatUpdatable is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get textureHalfFloatUpdatable() { @@ -1028,7 +1028,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#extTextureFloat is deprecated as it is always true + * @deprecated Always returns true. * @ignore */ get extTextureFloat() { @@ -1037,7 +1037,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#extStandardDerivatives is deprecated as it is always true. + * @deprecated Always returns true. * @ignore */ get extStandardDerivatives() { @@ -1046,8 +1046,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setBlendFunction is deprecated, use GraphicsDevice.setBlendState - * instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setBlendFunction(blendSrc, blendDst) { @@ -1060,8 +1059,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setBlendFunctionSeparate is deprecated, use - * GraphicsDevice.setBlendState instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha) { @@ -1074,8 +1072,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setBlendEquation is deprecated, use GraphicsDevice.setBlendState - * instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setBlendEquation(blendEquation) { @@ -1088,8 +1085,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setBlendEquationSeparate is deprecated, use - * GraphicsDevice.setBlendState instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setBlendEquationSeparate(blendEquation, blendAlphaEquation) { @@ -1102,8 +1098,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setColorWrite is deprecated, use GraphicsDevice.setBlendState - * instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setColorWrite(redWrite, greenWrite, blueWrite, alphaWrite) { @@ -1119,8 +1114,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setBlending is deprecated, use GraphicsDevice.setBlendState - * instead. + * @deprecated Use GraphicsDevice.setBlendState instead. * @ignore */ setBlending(blending) { @@ -1131,8 +1125,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setDepthWrite is deprecated, use GraphicsDevice.setDepthState - * instead. + * @deprecated Use GraphicsDevice.setDepthState instead. * @ignore */ setDepthWrite(write) { @@ -1143,8 +1136,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setDepthFunc is deprecated, use GraphicsDevice.setDepthState - * instead. + * @deprecated Use GraphicsDevice.setDepthState instead. * @ignore */ setDepthFunc(func) { @@ -1155,8 +1147,7 @@ class GraphicsDevice extends EventHandler { } /** - * @deprecated GraphicsDevice#setDepthTest is deprecated, use GraphicsDevice.setDepthState - * instead. + * @deprecated Use GraphicsDevice.setDepthState instead. * @ignore */ setDepthTest(test) { diff --git a/src/platform/graphics/render-target.js b/src/platform/graphics/render-target.js index 0e73a7ea3b2..3ef42caa68a 100644 --- a/src/platform/graphics/render-target.js +++ b/src/platform/graphics/render-target.js @@ -574,9 +574,9 @@ class RenderTarget { } /** - * @deprecated RenderTarget#flipY is deprecated, use the "origin" option of the RenderTarget - * constructor instead. Typical migration: flipY: !device.isWebGPU -> origin: - * RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU -> origin: RENDERTARGET_ORIGIN_BOTTOM. + * @deprecated Use the "origin" option of the RenderTarget constructor instead. Typical + * migration: flipY: !device.isWebGPU -> origin: RENDERTARGET_ORIGIN_TOP, flipY: device.isWebGPU + * -> origin: RENDERTARGET_ORIGIN_BOTTOM. * @ignore */ set flipY(value) { diff --git a/src/platform/graphics/texture.js b/src/platform/graphics/texture.js index dad3c454fb7..3016a51fb60 100644 --- a/src/platform/graphics/texture.js +++ b/src/platform/graphics/texture.js @@ -954,7 +954,7 @@ class Texture { } /** - * @deprecated Texture#rgbm is deprecated. Use Texture#type instead. + * @deprecated Use Texture#type instead. * @ignore */ set rgbm(value) { @@ -963,7 +963,7 @@ class Texture { } /** - * @deprecated Texture#rgbm is deprecated. Use Texture#type instead. + * @deprecated Use Texture#type instead. * @ignore */ get rgbm() { @@ -972,7 +972,7 @@ class Texture { } /** - * @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. + * @deprecated Use Texture#type instead. * @ignore */ set swizzleGGGR(value) { @@ -981,7 +981,7 @@ class Texture { } /** - * @deprecated Texture#swizzleGGGR is deprecated. Use Texture#type instead. + * @deprecated Use Texture#type instead. * @ignore */ get swizzleGGGR() { diff --git a/src/platform/graphics/vertex-format.js b/src/platform/graphics/vertex-format.js index 3dcfb969556..3f13f23fcb5 100644 --- a/src/platform/graphics/vertex-format.js +++ b/src/platform/graphics/vertex-format.js @@ -237,8 +237,7 @@ class VertexFormat { } /** - * @deprecated VertexFormat.defaultInstancingFormat was removed. Use - * VertexFormat.getDefaultInstancingFormat(graphicsDevice). + * @deprecated Use VertexFormat.getDefaultInstancingFormat(graphicsDevice). * @ignore */ static get defaultInstancingFormat() { diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 864cb57c1e3..81557c1817b 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -399,7 +399,7 @@ class GraphNode extends EventHandler { // ---- deprecated block start ---- /** - * @deprecated GraphNode#getChildren is deprecated. Use GraphNode#children instead. + * @deprecated Use GraphNode#children instead. * @ignore */ getChildren() { @@ -408,7 +408,7 @@ class GraphNode extends EventHandler { } /** - * @deprecated GraphNode#getName is deprecated. Use GraphNode#name instead. + * @deprecated Use GraphNode#name instead. * @ignore */ getName() { @@ -417,7 +417,7 @@ class GraphNode extends EventHandler { } /** - * @deprecated GraphNode#getPath is deprecated. Use GraphNode#path instead. + * @deprecated Use GraphNode#path instead. * @ignore */ getPath() { @@ -426,7 +426,7 @@ class GraphNode extends EventHandler { } /** - * @deprecated GraphNode#getRoot is deprecated. Use GraphNode#root instead. + * @deprecated Use GraphNode#root instead. * @ignore */ getRoot() { @@ -435,7 +435,7 @@ class GraphNode extends EventHandler { } /** - * @deprecated GraphNode#getParent is deprecated. Use GraphNode#parent instead. + * @deprecated Use GraphNode#parent instead. * @ignore */ getParent() { @@ -444,7 +444,7 @@ class GraphNode extends EventHandler { } /** - * @deprecated GraphNode#setName is deprecated. Use GraphNode#name instead. + * @deprecated Use GraphNode#name instead. * @ignore */ setName(name) { diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index 7961d18ae5d..2d4e19fe549 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -308,8 +308,8 @@ class Material { } /** - * @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. - * For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @deprecated Use Material.getShaderChunks instead. For example: + * material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") * @ignore */ set chunks(value) { @@ -318,8 +318,8 @@ class Material { } /** - * @deprecated Material.chunks has been removed, please use Material.getShaderChunks instead. - * For example: material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @deprecated Use Material.getShaderChunks instead. For example: + * material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") * @ignore */ get chunks() { diff --git a/src/scene/morph.js b/src/scene/morph.js index 7aa5ac23005..d57659bfcb0 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -264,7 +264,7 @@ class Morph extends RefCountedObject { // ---- deprecated block start ---- /** - * @deprecated Morph#getTarget is deprecated. Use Morph#targets instead. + * @deprecated Use Morph#targets instead. * @ignore */ getTarget(index) { diff --git a/src/scene/scene.js b/src/scene/scene.js index 61af20c871c..e835bfa7b53 100644 --- a/src/scene/scene.js +++ b/src/scene/scene.js @@ -924,7 +924,7 @@ class Scene extends EventHandler { // ---- deprecated block start ---- /** - * @deprecated Scene#defaultMaterial is deprecated. + * @deprecated No replacement is available. * @ignore */ get defaultMaterial() { @@ -933,7 +933,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. + * @deprecated Use Scene#fog.color instead. * @ignore */ set fogColor(value) { @@ -942,7 +942,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogColor is deprecated. Use Scene#fog.color instead. + * @deprecated Use Scene#fog.color instead. * @ignore */ get fogColor() { @@ -951,7 +951,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. + * @deprecated Use Scene#fog.end instead. * @ignore */ set fogEnd(value) { @@ -960,7 +960,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogEnd is deprecated. Use Scene#fog.end instead. + * @deprecated Use Scene#fog.end instead. * @ignore */ get fogEnd() { @@ -969,7 +969,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. + * @deprecated Use Scene#fog.start instead. * @ignore */ set fogStart(value) { @@ -978,7 +978,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogStart is deprecated. Use Scene#fog.start instead. + * @deprecated Use Scene#fog.start instead. * @ignore */ get fogStart() { @@ -987,7 +987,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. + * @deprecated Use Scene#fog.density instead. * @ignore */ set fogDensity(value) { @@ -996,7 +996,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#fogDensity is deprecated. Use Scene#fog.density instead. + * @deprecated Use Scene#fog.density instead. * @ignore */ get fogDensity() { @@ -1005,7 +1005,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered128(value) { @@ -1015,7 +1015,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered128 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered128() { @@ -1024,7 +1024,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered64(value) { @@ -1034,7 +1034,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered64 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered64() { @@ -1043,7 +1043,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered32(value) { @@ -1053,7 +1053,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered32 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered32() { @@ -1062,7 +1062,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered16(value) { @@ -1072,7 +1072,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered16 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered16() { @@ -1081,7 +1081,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered8(value) { @@ -1091,7 +1091,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered8 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered8() { @@ -1100,7 +1100,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ set skyboxPrefiltered4(value) { @@ -1110,7 +1110,7 @@ class Scene extends EventHandler { } /** - * @deprecated Scene#skyboxPrefiltered4 is deprecated. Use Scene#prefilteredCubemaps instead. + * @deprecated Use Scene#prefilteredCubemaps instead. * @ignore */ get skyboxPrefiltered4() { From 6dee62aab64846b75e16745c8fcbbeaa8a5b846b Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 11:12:24 +0100 Subject: [PATCH 08/10] docs: explain the jsdoc rule exemption in terms of what it protects The previous comment said requiring @param/@returns "would publish types for API we are steering callers away from", which does not say what actually goes wrong. JSDoc is the type source here, so adding those tags to a member that had no block overwrites the signature tsc inferred: supplying `@param {number} scalar` turns `scale(scalar: any): Vec3` into `scale(scalar: number): Vec3` in playcanvas.d.ts. Verified by building the declarations both ways. --- eslint.config.mjs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/eslint.config.mjs b/eslint.config.mjs index 80d358983af..86427700327 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -32,9 +32,12 @@ export default [ definedTags: [...new Set([...esmScriptTags, 'alpha', 'beta', 'category', 'import'])] } ], - // a deprecated member is documented only to carry the @deprecated marker into the type - // declarations - requiring @param/@returns there would publish types for API we are - // steering callers away from, so exempt those blocks + // JSDoc is the type source here, so adding @param/@returns to a member that had no + // block overwrites the signature tsc inferred for it: `scale(scalar: any)` in + // playcanvas.d.ts becomes `scale(scalar: number)`. A @deprecated block on a legacy + // member exists only to carry the marker into the declarations and must leave the + // published signature alone, so it is exempt from both rules. `inheritdoc` is the + // plugin's own default, preserved here. 'jsdoc/require-param': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }], 'jsdoc/require-returns': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }] } From 0eb36dafde414e6ef0f03d465aa70c22369e108e Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 11:20:34 +0100 Subject: [PATCH 09/10] docs: drop the jsdoc rule exemption, it was never needed require-param and require-returns only fired because the markers were single-line, where eslint-plugin-jsdoc parses @ignore as part of the @deprecated description and so sees no @ignore tag to skip the block on. Now that the blocks are multi-line the tag registers and both rules skip them, as a probe confirms: delete @ignore from one block and both errors return. eslint.config.mjs is now identical to main, so this PR is documentation only. --- eslint.config.mjs | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/eslint.config.mjs b/eslint.config.mjs index 86427700327..db30dea15f5 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -31,15 +31,7 @@ export default [ // extra tags, which this override would otherwise drop by replacing the rule definedTags: [...new Set([...esmScriptTags, 'alpha', 'beta', 'category', 'import'])] } - ], - // JSDoc is the type source here, so adding @param/@returns to a member that had no - // block overwrites the signature tsc inferred for it: `scale(scalar: any)` in - // playcanvas.d.ts becomes `scale(scalar: number)`. A @deprecated block on a legacy - // member exists only to carry the marker into the declarations and must leave the - // published signature alone, so it is exempt from both rules. `inheritdoc` is the - // plugin's own default, preserved here. - 'jsdoc/require-param': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }], - 'jsdoc/require-returns': ['error', { exemptedBy: ['deprecated', 'inheritdoc'] }] + ] } }, { From ae1b77be7acdf7f2019d69b80ecf8e52ecf183ff Mon Sep 17 00:00:00 2001 From: KPal Date: Mon, 3 Aug 2026 11:28:03 +0100 Subject: [PATCH 10/10] docs: give the deprecated members their real types The markers deliberately omitted @param/@returns so the inferred signatures would not move, which preserved `any` on every legacy member that takes an argument. `any` is the absence of information, not a type, so the members that published something untrue now carry accurate tags. Narrowed - these only reject calls that were already wrong at runtime: scale(scalar: any) -> (scalar: number) Vec2, Vec3, Vec4 setName(name: any) -> (name: string) getTarget(index: any) -> (index: number) setBlendFunction/Separate, setBlendEquation/Separate any -> number setColorWrite, setBlending, setDepthWrite, setDepthTest any -> boolean setDepthFunc any -> number static get defaultInstancingFormat(): any -> null get/set chunks: {} -> { [x: string]: string } Widened, and breaking for TypeScript callers: getParent(): GraphNode -> GraphNode | null That last one matches `get parent(): GraphNode | null` on the property that replaces it, so the legacy alias no longer claims to be non-nullable. Call sites chaining straight off it will need a null check. The other 45 members were left alone: tsc already infers their types correctly from bodies like `return this.fog.color`, so tags there would be inert. Verified: public API surface byte-identical at 5984 lines, typedoc 0 errors and 34 warnings, lint clean, 2210 tests passing, test:types passes. --- src/core/math/vec2.js | 2 ++ src/core/math/vec3.js | 2 ++ src/core/math/vec4.js | 2 ++ src/platform/graphics/graphics-device.js | 20 ++++++++++++++++++++ src/platform/graphics/vertex-format.js | 1 + src/scene/graph-node.js | 2 ++ src/scene/materials/material.js | 2 ++ src/scene/morph.js | 2 ++ 8 files changed, 33 insertions(+) diff --git a/src/core/math/vec2.js b/src/core/math/vec2.js index 805afd0c3fb..269862ac628 100644 --- a/src/core/math/vec2.js +++ b/src/core/math/vec2.js @@ -440,6 +440,8 @@ class Vec2 { /** * @deprecated Use Vec2#mulScalar instead. + * @param {number} scalar - The number to multiply by. + * @returns {Vec2} Self for chaining. * @ignore */ scale(scalar) { diff --git a/src/core/math/vec3.js b/src/core/math/vec3.js index 197ca2eb031..db2a4ee2af0 100644 --- a/src/core/math/vec3.js +++ b/src/core/math/vec3.js @@ -475,6 +475,8 @@ class Vec3 { /** * @deprecated Use Vec3#mulScalar instead. + * @param {number} scalar - The number to multiply by. + * @returns {Vec3} Self for chaining. * @ignore */ scale(scalar) { diff --git a/src/core/math/vec4.js b/src/core/math/vec4.js index 2256c6444a0..0869adb23b6 100644 --- a/src/core/math/vec4.js +++ b/src/core/math/vec4.js @@ -452,6 +452,8 @@ class Vec4 { /** * @deprecated Use Vec4#mulScalar instead. + * @param {number} scalar - The number to multiply by. + * @returns {Vec4} Self for chaining. * @ignore */ scale(scalar) { diff --git a/src/platform/graphics/graphics-device.js b/src/platform/graphics/graphics-device.js index 409ad237189..9be6f40f3d0 100644 --- a/src/platform/graphics/graphics-device.js +++ b/src/platform/graphics/graphics-device.js @@ -1047,6 +1047,8 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {number} blendSrc - The blend mode. Can be any of the BLENDMODE_* constants. + * @param {number} blendDst - The blend mode. Can be any of the BLENDMODE_* constants. * @ignore */ setBlendFunction(blendSrc, blendDst) { @@ -1060,6 +1062,10 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {number} blendSrc - The blend mode. Can be any of the BLENDMODE_* constants. + * @param {number} blendDst - The blend mode. Can be any of the BLENDMODE_* constants. + * @param {number} blendSrcAlpha - The blend mode. Can be any of the BLENDMODE_* constants. + * @param {number} blendDstAlpha - The blend mode. Can be any of the BLENDMODE_* constants. * @ignore */ setBlendFunctionSeparate(blendSrc, blendDst, blendSrcAlpha, blendDstAlpha) { @@ -1073,6 +1079,8 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {number} blendEquation - The blend equation. Can be any of the BLENDEQUATION_* + * constants. * @ignore */ setBlendEquation(blendEquation) { @@ -1086,6 +1094,10 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {number} blendEquation - The blend equation. Can be any of the BLENDEQUATION_* + * constants. + * @param {number} blendAlphaEquation - The blend equation. Can be any of the BLENDEQUATION_* + * constants. * @ignore */ setBlendEquationSeparate(blendEquation, blendAlphaEquation) { @@ -1099,6 +1111,10 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {boolean} redWrite - True to enable writing of the red channel and false otherwise. + * @param {boolean} greenWrite - True to enable writing of the green channel and false otherwise. + * @param {boolean} blueWrite - True to enable writing of the blue channel and false otherwise. + * @param {boolean} alphaWrite - True to enable writing of the alpha channel and false otherwise. * @ignore */ setColorWrite(redWrite, greenWrite, blueWrite, alphaWrite) { @@ -1115,6 +1131,7 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setBlendState instead. + * @param {boolean} blending - True to enable blending and false to disable it. * @ignore */ setBlending(blending) { @@ -1126,6 +1143,7 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setDepthState instead. + * @param {boolean} write - True to enable depth writing and false otherwise. * @ignore */ setDepthWrite(write) { @@ -1137,6 +1155,7 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setDepthState instead. + * @param {number} func - The depth testing function. Can be any of the FUNC_* constants. * @ignore */ setDepthFunc(func) { @@ -1148,6 +1167,7 @@ class GraphicsDevice extends EventHandler { /** * @deprecated Use GraphicsDevice.setDepthState instead. + * @param {boolean} test - True to enable depth testing and false otherwise. * @ignore */ setDepthTest(test) { diff --git a/src/platform/graphics/vertex-format.js b/src/platform/graphics/vertex-format.js index 3f13f23fcb5..65eb0db0de8 100644 --- a/src/platform/graphics/vertex-format.js +++ b/src/platform/graphics/vertex-format.js @@ -238,6 +238,7 @@ class VertexFormat { /** * @deprecated Use VertexFormat.getDefaultInstancingFormat(graphicsDevice). + * @returns {null} Always null. * @ignore */ static get defaultInstancingFormat() { diff --git a/src/scene/graph-node.js b/src/scene/graph-node.js index 81557c1817b..933953ef2cf 100644 --- a/src/scene/graph-node.js +++ b/src/scene/graph-node.js @@ -436,6 +436,7 @@ class GraphNode extends EventHandler { /** * @deprecated Use GraphNode#parent instead. + * @returns {GraphNode|null} The parent node, or null if this node has no parent. * @ignore */ getParent() { @@ -445,6 +446,7 @@ class GraphNode extends EventHandler { /** * @deprecated Use GraphNode#name instead. + * @param {string} name - The name to set. * @ignore */ setName(name) { diff --git a/src/scene/materials/material.js b/src/scene/materials/material.js index 2d4e19fe549..d028d0c0ddc 100644 --- a/src/scene/materials/material.js +++ b/src/scene/materials/material.js @@ -310,6 +310,7 @@ class Material { /** * @deprecated Use Material.getShaderChunks instead. For example: * material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @type {Object} * @ignore */ set chunks(value) { @@ -320,6 +321,7 @@ class Material { /** * @deprecated Use Material.getShaderChunks instead. For example: * material.getShaderChunks(SHADERLANGUAGE_GLSL).set("chunkName", "chunkCode") + * @type {Object} * @ignore */ get chunks() { diff --git a/src/scene/morph.js b/src/scene/morph.js index d57659bfcb0..6081cd3fd7f 100644 --- a/src/scene/morph.js +++ b/src/scene/morph.js @@ -265,6 +265,8 @@ class Morph extends RefCountedObject { /** * @deprecated Use Morph#targets instead. + * @param {number} index - The index of the morph target. + * @returns {MorphTarget} The morph target at the given index. * @ignore */ getTarget(index) {