docs: harden the JSDoc and published types that LLMs read

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.

scripts/esm/camera-frame.mjs

@@ -633,15 +633,20 @@ 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. 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
+ * 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 {

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 {
     /**

src/core/math/vec2.js

@@ -438,6 +438,12 @@ class Vec2 {
         return this;
     }
 
+    /**
+     * @deprecated Use Vec2#mulScalar instead.
+     * @param {number} scalar - The number to multiply by.
+     * @returns {Vec2} Self for chaining.
+     * @ignore
+     */
     scale(scalar) {
         Debug.deprecated('Vec2#scale is deprecated. Use Vec2#mulScalar instead.');
         return this.mulScalar(scalar);

src/core/math/vec3.js

@@ -473,6 +473,12 @@ class Vec3 {
         return this;
     }
 
+    /**
+     * @deprecated Use Vec3#mulScalar instead.
+     * @param {number} scalar - The number to multiply by.
+     * @returns {Vec3} Self for chaining.
+     * @ignore
+     */
     scale(scalar) {
         Debug.deprecated('Vec3#scale is deprecated. Use Vec3#mulScalar instead.');
         return this.mulScalar(scalar);

src/core/math/vec4.js

@@ -450,6 +450,12 @@ class Vec4 {
         return this;
     }
 
+    /**
+     * @deprecated Use Vec4#mulScalar instead.
+     * @param {number} scalar - The number to multiply by.
+     * @returns {Vec4} Self for chaining.
+     * @ignore
+     */
     scale(scalar) {
         Debug.deprecated('Vec4#scale is deprecated. Use Vec4#mulScalar instead.');
         return this.mulScalar(scalar);

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 {

src/extras/mini-stats/mini-stats.js

@@ -75,7 +75,13 @@ 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`.
+ *
+ * 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 {
     /**

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 {
     /**
@@ -1174,7 +1179,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:
      *

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 {
     /**

src/framework/asset/asset.js

@@ -554,6 +554,12 @@ 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, 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.
      * @param {object} [scope] - Scope object to use when calling the callback.

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,15 @@ class CameraComponent extends Component {
     /**
      * Convert a point from 3D world space to 2D screen space.
      *
+     * 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.
+     *
      * @param {Vec3} worldCoord - The world space coordinate.
      * @param {Vec3} [screenCoord] - 3D vector to receive screen coordinate result.
      * @returns {Vec3} The screen space coordinate.

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
  */

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) {

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}
      */

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)

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 {
     /**

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 {

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 {

src/platform/graphics/blend-state.js

@@ -462,6 +462,10 @@ class BlendState {
      */
     static NOBLEND = Object.freeze(new BlendState());
 
+    /**
+     * @deprecated Use BlendState.NOBLEND instead.
+     * @ignore
+     */
     static get DEFAULT() {
         Debug.deprecated('BlendState.DEFAULT is deprecated. Use BlendState.NOBLEND instead.');
         return BlendState.NOBLEND;