Docs: Add JSDoc for plugins (#1518)

* Add JSDoc for three/plugins

* Add notes and warnings

* Fix links

* Update config

* Perform link resolution on final step

Author: gkjohnson

src/core/renderer/tiles/TilesRendererBase.js

@@ -445,24 +445,28 @@ export class TilesRendererBase {
 
 		/**
 		 * LRU cache managing loaded tile lifecycle and memory eviction.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {LRUCache}
 		 */
 		this.lruCache = lruCache;
 
 		/**
-		 * Priority queue controlling concurrent tile downloads.
+		 * Priority queue controlling concurrent tile downloads. Max jobs defaults to `25`.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.downloadQueue = downloadQueue;
 
 		/**
-		 * Priority queue controlling concurrent tile parsing.
+		 * Priority queue controlling concurrent tile parsing. Max jobs defaults to `5`.
+		 * @note Cannot be modified once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.parseQueue = parseQueue;
 
 		/**
-		 * Priority queue controlling deferred tile child preprocessing.
+		 * Priority queue for expanding and initializing tiles for traversal. Max jobs defaults to `25`.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.processNodeQueue = processNodeQueue;
@@ -510,15 +514,21 @@ export class TilesRendererBase {
 		// options
 
 		/**
-		 * Target screen-space error in pixels. Tiles with a higher SSE are subdivided.
+		 * Target screen-space error in pixels to aim for when updating the geometry. Tiles will
+		 * not render if they are below this level of screen-space error. See the
+		 * {@link https://github.com/CesiumGS/3d-tiles/tree/master/specification#geometric-error geometric error section}
+		 * of the 3D Tiles specification for more information.
 		 * @type {number}
 		 */
 		this.errorTarget = 16.0;
 		this._errorThreshold = Infinity;
 
 		/**
-		 * If true, tiles are displayed at their current LOD while waiting for higher-detail
-		 * children to finish loading, rather than hiding them.
+		 * "Active tiles" are those that are loaded and available but not necessarily visible.
+		 * These tiles are useful for raycasting off-camera or for casting shadows. Active tiles
+		 * not currently in a camera frustum are removed from the scene as an optimization.
+		 * Setting this to `true` keeps them in the scene so they can be rendered from an outside
+		 * camera view not accounted for by the tiles renderer.
 		 * @type {boolean}
 		 */
 		this.displayActiveTiles = false;
@@ -530,20 +540,38 @@ export class TilesRendererBase {
 		this.maxDepth = Infinity;
 
 		/**
-		 * If true, uses an optimized traversal strategy that prioritizes distance over error.
+		 * **Experimental.** Enables an optimized tile loading strategy that loads only the tiles
+		 * needed for the current view, reducing memory usage and improving initial load times.
+		 * Tiles are loaded independently based on screen-space error without requiring all parent
+		 * tiles to load first. Prevents visual gaps and flashing during camera movement.
+		 *
+		 * Based in part on {@link https://cesium.com/learn/cesium-native/ref-doc/selection-algorithm-details.html Cesium Native tile selection}.
+		 *
+		 * Default is `false`, which uses the previous approach of loading all parent and sibling
+		 * tiles for guaranteed smooth transitions.
+		 * @warn Setting is currently incompatible with plugins that split tiles and on-the-fly generate and
+		 * dispose of child tiles including the `ImageOverlayPlugin` `enableTileSplitting` setting,
+		 * `QuantizedMeshPlugin`, & `ImageFormatPlugin` subclasses (XYZ, TMS, etc). Any tile sets
+		 * that share caches or queues must also use the same setting.
 		 * @type {boolean}
 		 */
 		this.optimizedLoadStrategy = false;
 
 		/**
-		 * If true, sibling tiles of visible tiles are also loaded to reduce pop-in during camera movement.
+		 * **Experimental.** When `true`, sibling tiles are loaded together to prevent gaps during
+		 * camera movement. When `false`, only visible tiles are loaded, minimizing memory but
+		 * potentially causing brief gaps during rapid movement.
+		 *
+		 * Only applies when `optimizedLoadStrategy` is enabled.
 		 * @type {boolean}
 		 */
 		this.loadSiblings = true;
 
 		/**
-		 * Maximum number of tile children to preprocess per `update` call. Excess tiles are deferred
-		 * to `processNodeQueue`.
+		 * The number of tiles to process immediately when traversing the tile set to determine
+		 * what to render. Lower numbers prevent frame hiccups caused by processing too many tiles
+		 * at once when a new tile set is available, while higher values process more tiles
+		 * immediately so data can be downloaded and displayed sooner.
 		 * @type {number}
 		 */
 		this.maxTilesProcessed = 250;

src/core/renderer/utilities/BatchTable.js

@@ -67,7 +67,9 @@ export class BatchTable extends FeatureTable {
 	}
 
 	/**
-	 * Returns all batch table properties for the given feature id as an object.
+	 * Returns an object with all properties of the batch table and its extensions for the
+	 * given feature id. A `target` object can be specified to store the result. Throws if
+	 * `id` is out of bounds.
 	 * @param {number} id - Feature index (0 to count - 1)
 	 * @param {Object} [target={}] - Optional object to write properties into
 	 * @returns {Object}
@@ -104,9 +106,10 @@ export class BatchTable extends FeatureTable {
 	}
 
 	/**
-	 * Returns the full typed array of values for the given property key across all features.
+	 * Returns the array of values for the given property key across all features. Returns
+	 * `null` if the key is not in the table.
 	 * @param {string} key
-	 * @returns {number | string | ArrayBufferView}
+	 * @returns {Array | TypedArray | null}
 	 */
 	getPropertyArray( key ) {
 

src/core/renderer/utilities/LRUCache.js

@@ -69,12 +69,14 @@ class LRUCache {
 
 		/**
 		 * Minimum total bytes to retain after eviction.
+		 * @note Only works with three.js r166 or higher.
 		 * @type {number}
 		 */
 		this.minBytesSize = 0.3 * GIGABYTE_BYTES;
 
 		/**
 		 * Maximum total bytes before eviction is triggered.
+		 * @note Only works with three.js r166 or higher.
 		 * @type {number}
 		 */
 		this.maxBytesSize = 0.4 * GIGABYTE_BYTES;

src/core/renderer/utilities/PriorityQueue.js

@@ -79,7 +79,10 @@ export class PriorityQueue {
 		this.priorityCallback = null;
 
 		/**
-		 * Callback used to schedule a deferred job run. Defaults to `requestAnimationFrame`.
+		 * Callback used to schedule when to run jobs next, so more work doesn't happen in a
+		 * single frame than there is time for. Defaults to `requestAnimationFrame`. Should be
+		 * overridden in scenarios where `requestAnimationFrame` is not reliable, such as when
+		 * running in WebXR.
 		 * @type {SchedulingCallback}
 		 */
 		this.schedulingCallback = func => {

src/three/plugins/CesiumIonAuthPlugin.js

@@ -2,6 +2,18 @@ import { CesiumIonAuthPlugin as CesiumIonAuthPluginImpl } from '3d-tiles-rendere
 import { TMSTilesPlugin } from './images/EPSGTilesPlugin.js';
 import { QuantizedMeshPlugin } from './QuantizedMeshPlugin.js';
 
+/**
+ * Plugin for authenticating requests to Cesium Ion. Handles token refresh, asset
+ * endpoint resolution, and attribution collection. Auto-registration of terrain and
+ * imagery plugins via `assetTypeHandler` is deprecated — provide a custom handler
+ * instead.
+ * @param {Object} [options]
+ * @param {string} [options.apiToken] Cesium Ion API token.
+ * @param {string|null} [options.assetId=null] Cesium Ion asset ID, or `null` when using an explicit root URL.
+ * @param {boolean} [options.autoRefreshToken=false] Automatically refresh the token on 4xx errors.
+ * @param {boolean} [options.useRecommendedSettings=true] Apply recommended renderer settings for Cesium Ion assets.
+ * @param {Function} [options.assetTypeHandler] Callback `(type, tiles, asset)` invoked for non-3DTILES asset types.
+ */
 export class CesiumIonAuthPlugin extends CesiumIonAuthPluginImpl {
 
 	constructor( options = {} ) {

src/three/plugins/DebugTilesPlugin.js

@@ -59,6 +59,25 @@ const ColorModes = Object.freeze( {
 	LOAD_ORDER,
 } );
 
+/**
+ * Plugin that adds visual debugging aids to a `TilesRenderer`: bounding-volume
+ * helpers (box, sphere, region), tile color modes based on depth/error/distance/load
+ * order, and an unlit rendering mode. Color modes are available via the static
+ * `ColorModes` property.
+ * @param {Object} [options]
+ * @param {boolean} [options.displayBoxBounds=false] Show OBB bounding-box helpers.
+ * @param {boolean} [options.displaySphereBounds=false] Show bounding-sphere helpers.
+ * @param {boolean} [options.displayRegionBounds=false] Show bounding-region helpers.
+ * @param {boolean} [options.displayParentBounds=false] Also show ancestor bounding volumes for visible tiles.
+ * @param {number} [options.colorMode=ColorModes.NONE] Initial tile color mode.
+ * @param {number} [options.boundsColorMode=ColorModes.NONE] Color mode applied to bounding-volume helpers.
+ * @param {number} [options.maxDebugDepth=-1] Maximum tree depth for depth-based coloring (`-1` = auto).
+ * @param {number} [options.maxDebugDistance=-1] Maximum distance for distance-based coloring (`-1` = auto).
+ * @param {number} [options.maxDebugError=-1] Maximum error for error-based coloring (`-1` = auto).
+ * @param {Function|null} [options.customColorCallback=null] Callback `( tile, mesh )` used when `colorMode` is `CUSTOM_COLOR`.
+ * @param {boolean} [options.unlit=false] Replace tile materials with unlit `MeshBasicMaterial`.
+ * @param {boolean} [options.enabled=true] Whether the plugin is active on init.
+ */
 export class DebugTilesPlugin {
 
 	static get ColorModes() {
@@ -232,6 +251,12 @@ export class DebugTilesPlugin {
 		this.customColorCallback = options.customColorCallback;
 		this.unlit = options.unlit;
 
+		/**
+		 * Maps a normalized [0, 1] value to a `Color` for debug visualizations. Defaults to
+		 * a black-to-white gradient. Replace with a custom function to use a different color
+		 * ramp.
+		 * @type {( val: number, target: Color ) => void}
+		 */
 		this.getDebugColor = ( value, target ) => {
 
 			target.setRGB( value, value, value );

src/three/plugins/GLTFExtensionsPlugin.js

@@ -3,6 +3,19 @@ import { GLTFStructuralMetadataExtension } from './gltf/GLTFStructuralMetadataEx
 import { GLTFMeshFeaturesExtension } from './gltf/GLTFMeshFeaturesExtension.js';
 import { GLTFCesiumRTCExtension } from './gltf/GLTFCesiumRTCExtension.js';
 
+/**
+ * Plugin for automatically adding common extensions and loaders for 3D Tiles to the
+ * `GLTFLoader` used for parsing tile geometry. A `DRACOLoader` can be provided to
+ * support loading Draco-compressed point cloud files.
+ * @param {Object} [options]
+ * @param {boolean} [options.metadata=true] Enable the `EXT_structural_metadata` and `EXT_mesh_features` extensions.
+ * @param {boolean} [options.rtc=true] Enable the `CESIUM_RTC` extension.
+ * @param {Array} [options.plugins=[]] Additional GLTF loader plugins to pass to `GLTFLoader.register`.
+ * @param {Object} [options.dracoLoader=null] A `DRACOLoader` instance for Draco-compressed geometry.
+ * @param {Object} [options.ktxLoader=null] A `KTX2Loader` instance for KTX2-compressed textures.
+ * @param {Object} [options.meshoptDecoder=null] A `MeshoptDecoder` for Meshopt-compressed meshes.
+ * @param {boolean} [options.autoDispose=true] Automatically dispose the DRACO and KTX loaders on `dispose()`.
+ */
 export class GLTFExtensionsPlugin {
 
 	constructor( options ) {

src/three/plugins/LoadRegionPlugin.js

@@ -1,6 +1,12 @@
 import { Ray, Sphere } from 'three';
 import { OBB } from '3d-tiles-renderer/three';
 
+/**
+ * Plugin that restricts tile loading and traversal to one or more geometric regions
+ * (`SphereRegion`, `RayRegion`, `OBBRegion`). Only tiles that intersect an active
+ * region are loaded and refined. Regions marked as masks additionally prevent tiles
+ * outside them from loading.
+ */
 export class LoadRegionPlugin {
 
 	constructor() {
@@ -111,6 +117,14 @@ export class LoadRegionPlugin {
 }
 
 // Definitions of predefined regions
+
+/**
+ * Abstract base class for `LoadRegionPlugin` regions. Subclass and override
+ * `intersectsTile` to define custom load regions.
+ * @param {Object} [options]
+ * @param {number} [options.errorTarget=10] Geometric error target used when this region controls refinement.
+ * @param {boolean} [options.mask=false] When `true`, tiles outside this region are suppressed (mask mode).
+ */
 export class BaseRegion {
 
 	constructor( options = {} ) {
@@ -152,6 +166,13 @@ export class BaseRegion {
 
 }
 
+/**
+ * A spherical load region. Only tiles that intersect `sphere` are loaded.
+ * @param {Object} [options]
+ * @param {Sphere} [options.sphere] The sphere volume; defaults to an empty sphere at the origin.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class SphereRegion extends BaseRegion {
 
 	constructor( options = {} ) {
@@ -181,6 +202,13 @@ export class SphereRegion extends BaseRegion {
 
 }
 
+/**
+ * A ray-based load region. Only tiles that intersect `ray` are loaded.
+ * @param {Object} [options]
+ * @param {Ray} [options.ray] The ray; defaults to a ray at the origin pointing in +Z.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class RayRegion extends BaseRegion {
 
 	constructor( options = {} ) {
@@ -210,6 +238,13 @@ export class RayRegion extends BaseRegion {
 
 }
 
+/**
+ * An oriented bounding-box load region. Only tiles that intersect `obb` are loaded.
+ * @param {Object} [options]
+ * @param {OBB} [options.obb] The oriented bounding box; defaults to an empty OBB at the origin.
+ * @param {number} [options.errorTarget=10] Geometric error target for tiles inside the region.
+ * @param {boolean} [options.mask=false] Mask mode — suppresses tiles outside this region.
+ */
 export class OBBRegion extends BaseRegion {
 
 	constructor( options = {} ) {

src/three/plugins/QuantizedMeshPlugin.js

@@ -77,6 +77,17 @@ function getContentUrl( x, y, level, version, layer ) {
 
 }
 
+/**
+ * Plugin that adds support for the Cesium quantized-mesh terrain format. Fetches the
+ * `layer.json` descriptor from the tileset root and dynamically generates 3D Tiles
+ * tile content from quantized-mesh buffers.
+ * @param {Object} [options]
+ * @param {boolean} [options.useRecommendedSettings=true] Apply recommended error and fetch settings for terrain.
+ * @param {number|null} [options.skirtLength=null] Override skirt length in metres; defaults to tile geometric error.
+ * @param {boolean} [options.smoothSkirtNormals=true] Blend skirt normals with tile surface for smoother edges.
+ * @param {boolean} [options.generateNormals=true] Compute vertex normals for the terrain mesh.
+ * @param {boolean} [options.solid=false] Generate a solid closed mesh (adds a bottom cap).
+ */
 export class QuantizedMeshPlugin {
 
 	constructor( options = {} ) {

src/three/plugins/ReorientationPlugin.js

@@ -2,6 +2,23 @@ import { Sphere } from 'three';
 import { OBJECT_FRAME } from '3d-tiles-renderer/three';
 
 const sphere = /* @__PURE__ */ new Sphere();
+
+/**
+ * Plugin for automatically re-orienting and re-centering the tileset to make it visible
+ * near the origin and facing the right direction. If `lat`/`lon` are provided the
+ * tileset is placed at that geographic location; otherwise the plugin tries to determine
+ * if the tileset is on the globe surface and estimates the coordinates. If no coordinates
+ * can be determined the tileset is oriented so the given `up` axis aligns to three.js' +Y.
+ * @param {Object} [options]
+ * @param {number|null} [options.lat=null] Latitude in radians of the surface point to orient to (requires `lon`).
+ * @param {number|null} [options.lon=null] Longitude in radians of the surface point to orient to (requires `lat`).
+ * @param {number} [options.height=0] Height in metres above the ellipsoid surface.
+ * @param {string} [options.up='+z'] Axis to orient toward three.js +Y when no lat/lon is available. Valid values are `±x`, `±y`, `±z`.
+ * @param {boolean} [options.recenter=true] Whether to reposition the tileset to the origin.
+ * @param {number} [options.azimuth=0] Azimuth rotation in radians.
+ * @param {number} [options.elevation=0] Elevation rotation in radians.
+ * @param {number} [options.roll=0] Roll rotation in radians.
+ */
 export class ReorientationPlugin {
 
 	constructor( options ) {
@@ -118,6 +135,16 @@ export class ReorientationPlugin {
 
 	}
 
+	/**
+	 * Centers the tileset such that the given coordinates are positioned at the origin
+	 * with X facing west and Z facing north.
+	 * @param {number} lat Latitude in radians.
+	 * @param {number} lon Longitude in radians.
+	 * @param {number} [height=0] Height in metres above the ellipsoid surface.
+	 * @param {number} [azimuth=0] Azimuth rotation in radians.
+	 * @param {number} [elevation=0] Elevation rotation in radians.
+	 * @param {number} [roll=0] Roll rotation in radians.
+	 */
 	transformLatLonHeightToOrigin( lat, lon, height = 0, azimuth = 0, elevation = 0, roll = 0 ) {
 
 		const { group, ellipsoid } = this.tiles;