Gets whether the frame buffer has an alpha channel.
The alpha flag.
Sets whether the frame buffer has an alpha channel, which is what lets the page show through wherever the scene has not drawn. Read only when the application boots.
The alpha flag.
Gets whether the frame buffer is anti-aliased.
The antialias flag.
Sets whether the frame buffer is anti-aliased. Read only when the application boots.
The antialias flag.
The PlayCanvas application instance. null until the element is ready, and again once it
has been removed from the document — await whenReady or the element's ready()
promise before accessing it.
The application instance, or null.
Gets the id of the <pc-asset> holding the area light lookup tables, whose loading also
enables area lights for the application.
The asset ID.
Sets the id of the <pc-asset> holding the area light lookup tables, whose loading also
enables area lights for the application, so <pc-light> elements with a rect, disk or
sphere shape render as intended. The asset is a JSON file with LTC_MAT_1 and LTC_MAT_2
arrays, like the PlayCanvas Engine examples' area-light-luts.json. The tables apply to the
whole application and, when set before the application boots, load along with the other
assets. Unlike the frame buffer options this applies immediately: clearing it switches area
lights off again, though tables already handed to the engine stay in place. Devices that
cannot render area lights ignore the switch, and omni and spot area lights stay punctual
there.
The asset ID.
Gets the graphics backend.
The graphics backend.
Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU is not supported by the browser. Read only when the application boots.
The graphics backend ('webgpu', 'webgl2', or 'null').
The nearest ancestor <pc-app> element, or null if this element has no <pc-app>
ancestor. The search starts at the parent, so an element never resolves to itself.
The closest app element, or null.
The nearest ancestor element that fronts an entity — <pc-entity>, <pc-model> or
<pc-node> — or null if this element has no such ancestor. The search starts at the
parent, so an element never resolves to itself.
The closest entity-fronting element, or null.
Gets whether the frame buffer has a depth buffer.
The depth buffer flag.
Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which surface is nearest the camera. Read only when the application boots.
The depth buffer flag.
Gets whether the application announces itself to developer tools, such as the PlayCanvas Inspector browser extension, so they can find and inspect it.
Whether the application announces itself to developer tools.
Sets whether the application announces itself to developer tools, such as the PlayCanvas
Inspector browser extension, so they can find and inspect it. Set false to keep a
production page from announcing itself. This is an opt-out, not a protection: code running on
the page can still reach the application, through this element's app property for one.
Read only when the application boots. Defaults to true.
Whether the application announces itself to developer tools.
Gets whether the application shows its built-in loading bar while it boots and preloads its assets.
The loading bar flag.
Sets whether the application shows its built-in loading bar while it boots and preloads its
assets. Enabled by default; setting false removes the bar immediately, while setting
true has no effect until the element is next connected. The bar can be themed with the
CSS custom properties --pc-loading-bar-color, --pc-loading-bar-background and
--pc-loading-bar-height.
The loading bar flag.
The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
preloading begins (and again once the element has been removed from the document), and 1
once preloading has finished — including when there was nothing to preload. Read this to
initialize a loading UI; subsequent updates arrive via the progress event.
The preload progress.
Gets the cap on the pixel ratio the application renders at.
The maximum pixel ratio.
Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
smaller of this value and the display's own device pixel ratio, so the default of Infinity
renders at full physical resolution, 1 renders at CSS resolution, and an intermediate
value such as 2 keeps a dense display sharp without paying for every one of its pixels.
Must be greater than 0. Unlike the other graphics options, this applies immediately.
The maximum pixel ratio.
Gets the scale on the time the physics simulation advances by each frame, applied on top of
time-scale: 0 pauses physics alone while the rest of the application keeps running.
The physics time scale.
Sets the scale on the time the physics simulation advances by each frame: below 1 is slow
motion, above 1 speeds it up and 0 pauses it while the rest of the application keeps
running. Applied on top of time-scale. Defaults to 1.
The physics time scale.
Gets how the application decides whether to pick the scene under the pointer, which it
does to dispatch pointer events on entity elements: auto picks for an event type while a
listener for it is registered on an entity element or <pc-scene>, always for every
pointer event, and none never.
When to pick.
Sets when the application picks the scene under the pointer, which it does to dispatch pointer events on entity elements. Picking renders the scene again, so by default it only happens while something listens:
auto (the default) picks for an event type while a listener for it is registered on an
entity element or on <pc-scene> - with addEventListener, an inline attribute such as
onclick, or a handler property such as onpointerenter.always picks for every pointer event. Listeners the element cannot see need it: one on
the document or on another element outside the scene, or a framework's delegated handler,
such as React's onPointerMove. React's onClick does not need it, because React also
sets the onclick property of the element it is on.none never picks, so no pointer events are dispatched on entities.Applies from the next pointer event.
When to pick ('auto', 'always' or 'none').
Gets whether the frame buffer has a stencil buffer.
The stencil buffer flag.
Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI masking need. Read only when the application boots.
The stencil buffer flag.
Gets the scale on the time the application advances by each frame. Scripts, animation and physics all advance by the scaled time, so 0 pauses all three together.
The time scale.
Sets the scale on the time the application advances by each frame. Scripts, animation and
physics all advance by the scaled time, so below 1 is slow motion, above 1 speeds it up and
0 pauses all three together. To pause or slow down physics alone, use physics-time-scale.
Defaults to 1.
The time scale.
Gets whether asset requests send credentials (cookies and HTTP authentication) to other
origins, which applies to every application on the page. Once the application has booted,
this reports the engine's page-wide setting - which another <pc-app> may have switched on -
rather than this element's own attribute.
Whether asset requests send credentials.
Sets whether asset requests send credentials (cookies and HTTP authentication) to other
origins, which the asset server must allow through CORS. The engine keeps this in its shared
HTTP client, so it applies to every application on the page. Defaults to false.
Whether asset requests send credentials.
Protected_Called when the element is fully initialized and ready. Subclasses should call this when
they're ready. Resolves the ready promise and dispatches a bubbling, composed ready
event. Signals at most once per readiness cycle: a repeat call before _resetReady
has re-armed the promise does nothing.
Protected_Returns the ready promise to its pending state. Subclasses should call this when the
resource their readiness announced is torn down (typically from disconnectedCallback),
so that a later re-initialization can signal readiness again. Does nothing while the
promise is still pending — an in-flight waiter carries over to the next readiness cycle
rather than being stranded on a promise nothing will ever resolve.
Returns the <pc-entity>, <pc-model> or <pc-node> element whose backing entity is
entity, or null if the entity is not fronted by an element of this application - for
example, an unbound node inside a model's instantiated hierarchy, or an entity created
through the engine API.
The entity to look up.
The element fronting the entity, or null.
Returns a promise that resolves with this element when it's ready. This is the low-level primitive underlying whenReady, which is the recommended way to wait for elements.
Readiness tracks the element's current lifecycle: once a ready element is torn down (for example by removing it from the document), this returns a fresh promise that resolves when the element is next ready. A promise obtained earlier stays resolved — call this again after re-inserting an element rather than reusing a promise from before its removal.
A promise that resolves with this element when it's ready.
The AppElement interface provides properties and methods for manipulating
<pc-app>elements. The AppElement interface also inherits the properties and methods of the HTMLElement interface.The element is sized like a replaced element such as
<video>: a block-level box that the page's CSS controls, 300x150 by default. The application's canvas always fills the element, and the drawing buffer resolution follows the element's size (capped bymax-pixel-ratio), tracked live via a ResizeObserver — so the element can be embedded at any size, resized by its container, or made fullscreen with ordinary CSS such aswidth: 100vw; height: 100dvh.Pointer input over the canvas is hit-tested against the scene and dispatched as pointer events on the entity elements under the pointer, where they behave like the DOM's own pointer events;
pickingcontrols when that happens. The canvas keeps receiving its native events too, so a listener on this element sees both kinds -event.targettells them apart.Fires
progress - Fired while the application preloads its assets.
loadedandtotalare asset counts, not bytes, and an asset that fails to load still counts as loaded. Fired at least once per boot, and the final event always hasloadedequal tototal. Does not bubble.Fires
error - Fired when the application cannot boot because no graphics device could be created (for example, a browser with WebGL disabled).
messagenames the requested backends anderrorholds the underlying failure. The element never becomes ready andappstaysnull— listen for this event to show a fallback UI. Removing the element and re-inserting it retries the boot with its current attributes. Does not bubble.