# TilesRendererBase

class in `3d-tiles-renderer/core`

```js
import { TilesRendererBase } from '3d-tiles-renderer/core';
```

Base class for 3D Tiles renderers. Manages tile loading, caching, traversal,
and a plugin system for extending rendering behavior. Engine-specific renderers
extend this class to add camera projection, scene management, and tile display.

## Constructor

```js
new TilesRendererBase( url?: string )
```

- `url`, `string`, optional, default `null`: URL of the root tileset JSON to load.

## Properties

### .root: Tile | null

readonly

Root tile of the loaded root tileset, or null if not yet loaded.

### .loadProgress: number

readonly

Fraction of tiles loaded since the last idle state, from 0 (nothing loaded) to 1 (all loaded).

### .downloadQueue: DownloadPriorityQueue

Download queue managing concurrent tile downloads per server origin. Max jobs per origin
defaults to `25`.

> **Note:** Cannot be replaced once `update()` has been called for the first time.

### .rootTileset: Tileset | null

readonly

The loaded root tileset object, or null if not yet loaded.

### .fetchOptions: RequestInit

default `{}`

Options passed to `fetch` when loading tile and tileset resources.

### .visibleTiles: Set<Tile>

readonly

Set of all tiles that are currently visible.

### .activeTiles: Set<Tile>

readonly

Set of all tiles that are currently active (displayed as a stand-in while children load).

### .lruCache: LRUCache

LRU cache managing loaded tile lifecycle and memory eviction.

> **Note:** Cannot be replaced once `update()` has been called for the first time.

### .parseQueue: PriorityQueue

Priority queue controlling concurrent tile parsing. Max jobs defaults to `5`.

> **Note:** Cannot be modified once `update()` has been called for the first time.

### .processNodeQueue: PriorityQueue

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.

### .stats: Object

Loading and rendering statistics updated each frame. Fields:
- `inCache` — tiles currently in the LRU cache
- `queued` — tiles queued for download
- `downloading` — tiles currently downloading
- `parsing` — tiles currently being parsed
- `loaded` — tiles that have finished loading
- `failed` — tiles that failed to load
- `inFrustum` — tiles inside the camera frustum after the last update
- `used` — tiles visited during the last traversal
- `active` — tiles currently set as active
- `visible` — tiles currently visible
- `refused` — tiles the last update wanted to load but could not queue because the cache was full

### .errorTarget: number

default `16`

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
`geometric error section`
of the 3D Tiles specification for more information.

### .errorFalloff: number

default `0`

Maximum screen-space error in pixels subtracted from distant tiles. Set to 0 to disable.
Comparable to Cesium's "dynamicScreenSpaceError" settings.

`error -= errorFalloff * ( 1 - e ^ -( distance * errorFalloffDensity )² )`

> [!WARN]
> Experimental and may change.

### .errorFalloffDensity: number

default `2e-4`

Distance scale for the "errorFalloff" curve, in inverse meters. Larger values affect
tiles closer to the camera.
Comparable to Cesium's "dynamicScreenSpaceError" settings.

> [!WARN]
> Experimental and may change.

### .displayActiveTiles: boolean

default `false`

"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.

### .maxDepth: number

default `Infinity`

Maximum depth in the tile hierarchy to traverse. Tiles deeper than this are skipped.

### .loadSiblings: boolean

default `true`

**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. Implicitly treated as `true` when
`loadAncestors` is enabled.

### .loadAncestors: boolean

default `true`

**Experimental.** When `true`, ancestor tiles are queued for download and displayed as a
fallback while children are loading — similar to the behavior of the standard load
strategy. Increases memory usage but provides smoother transitions on first load.
Implicitly enables sibling loading to prevent flickering during camera movement.

### .maxTilesProcessed: number

default `250`

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.

## Methods

### .registerPlugin

```js
.registerPlugin( plugin: Object )
```

Registers a plugin with this renderer. Plugins are inserted in priority order and
receive lifecycle callbacks throughout the tile loading and rendering process.
A plugin instance may only be registered to one renderer at a time.

- `plugin`, `Object`

### .unregisterPlugin

```js
.unregisterPlugin( plugin: Object | string ): boolean
```

Removes a registered plugin. Calls `plugin.dispose()` if defined.
Accepts either the plugin instance or its string name.
Returns true if the plugin was found and removed.

- `plugin`, `Object | string`

### .getPluginByName

```js
.getPluginByName( name: string ): Object | null
```

Returns the first registered plugin whose `name` property matches, or null.

- `name`, `string`

### .traverse

```js
.traverse( beforecb?: TileBeforeCallback | null, aftercb?: TileAfterCallback | null )
```

Iterates over all tiles in the loaded hierarchy. `beforecb` is called before
descending into a tile's children; returning true from it skips the subtree.
`aftercb` is called after all children have been visited.

- `beforecb`, `TileBeforeCallback | null`, optional
- `aftercb`, `TileAfterCallback | null`, optional

### .getAttributions

```js
.getAttributions( target?: Array<{type: string, value: any}> ): Array<{type: string, value: any}>
```

Collects attribution data from all registered plugins into `target` and returns it.

- `target`, `Array<{type: string, value: any}>`, optional

### .update

```js
.update(  )
```

Runs the tile traversal and update loop. Should be called once per frame after
camera matrices have been updated. Triggers tile loading, visibility updates,
and LRU cache eviction.

### .resetFailedTiles

```js
.resetFailedTiles(  )
```

Resets any tiles that previously failed to load so they will be retried on the next `update`.

### .dispose

```js
.dispose(  )
```

Disposes all loaded tiles and unregisters all plugins. The renderer should not
be used after calling this.

### .dispatchEvent

```js
.dispatchEvent( e: Object )
```

Dispatches an event to all registered listeners for the given event type.

- `e`, `Object`

### .addEventListener

```js
.addEventListener( name: string, callback: EventCallback )
```

Registers a listener for the given event type.

- `name`, `string`
- `callback`, `EventCallback`

### .removeEventListener

```js
.removeEventListener( name: string, callback: EventCallback )
```

Removes a previously registered event listener.

- `name`, `string`
- `callback`, `EventCallback`

## Events

### needs-update

Fired when the renderer determines a new render is required — e.g. after a tile loads.

### load-tileset

Fired when any tileset JSON finishes loading.

- `tileset`, `Tileset`: The loaded tileset object.
- `url`, `string`: The URL from which the tileset was loaded.

### load-root-tileset

Fired when the root tileset JSON finishes loading.

- `tileset`, `Tileset`: The loaded root tileset object.
- `url`, `string`: The URL from which the tileset was loaded.

### tiles-load-start

Fired when tile downloads begin after a period of inactivity.

### tiles-load-end

Fired when all pending tile downloads and parses have completed.

### tile-download-start

Fired when a tile content download begins.

- `tile`, `Tile`: The tile being downloaded.
- `url`, `string`: The URL being fetched.

### load-model

Fired when a tile's renderable content (model/scene) is created.
The `scene` type is engine-specific (e.g. `THREE.Group` in three.js).

- `scene`, `Object`: The engine-specific scene object created for this tile.
- `tile`, `Tile`: The tile the scene belongs to.
- `url`, `string`: The URL the content was loaded from.

### dispose-model

Fired when a tile's renderable content is about to be removed and destroyed.
The `scene` type is engine-specific (e.g. `THREE.Group` in three.js).

- `scene`, `Object`: The engine-specific scene object being disposed.
- `tile`, `Tile`: The tile the scene belonged to.

### tile-visibility-change

Fired when a tile transitions between visible and hidden.
The `scene` type is engine-specific (e.g. `THREE.Group` in three.js).

- `scene`, `Object`: The engine-specific scene object.
- `tile`, `Tile`: The tile whose visibility changed.
- `visible`, `boolean`: Whether the tile is now visible.

### update-before

Fired at the start of each `update()` call, before traversal begins.

### update-after

Fired at the end of each `update()` call, after traversal completes.

### load-error

Fired when a tile or tileset fails to load.

- `tile`, `Tile | null`: The tile that failed, or null if a root tileset failed.
- `error`, `Error`: The error that occurred.
- `url`, `string | URL`: The URL that failed to load.