<pc-screen>

The <pc-screen> tag adds a screen component, the root of a 2D user interface. The <pc-element> entities below it are laid out in its units, and drawn either over the camera's view or on a panel in the scene.

A <pc-screen> without attributes is a world-space screen: a 640 × 320 panel in its entity's local units, so at the entity's default scale it is 640 meters wide, and a 32 × 32 element on it is 32 meters across. For a HUD or a menu, set screen-space, as the example below does. For a panel in the world, scale the entity down — see Size and Scale.

Usage

It must be a direct child of a <pc-entity>, a <pc-model> or a <pc-node>.

Attributes

Attribute	Type	Default	Description
`enabled`	Boolean	`"true"`	Enabled state of the component
`priority`	Number	`"0"`	Drawing order among screens, from 0 to 127: a screen with a higher priority is drawn over screens with a lower one, and its elements receive input first
`reference-resolution`	Vector2	`"640 320"`	The resolution the UI is laid out for, as "Width Height" values. With `scale-mode="blend"`, the contents are scaled by the size of the canvas relative to it
`resolution`	Vector2	`"640 320"`	Size of a world-space screen in its entity's local units, as "Width Height" values. A screen-space screen takes its resolution from the canvas, so this has no effect on one
`scale-blend`	Number	`"0.5"`	With `scale-mode="blend"`, how the width and the height of the canvas are weighted in the scale, from 0 (width only) to 1 (height only). 0.5 weights them equally. Ignored when `scale-mode` is `"none"`
`scale-mode`	Enum	`"none"`	How the screen scales its contents: `"none"` \| `"blend"`. `"none"` doesn't scale them: on a screen-space screen, one unit is one pixel of the canvas's drawing buffer. `"blend"` scales them by the size of the canvas relative to `reference-resolution`, weighted by `scale-blend`, which is what keeps a UI laid out at one resolution usable at another. Requires `screen-space`
`screen-space`	Boolean	`"false"`	Whether the screen is drawn over the camera's view, at the size of the canvas. Otherwise it is a world-space screen, placed in the scene by its entity's transform and sized by `resolution`

Scaling only applies to screen-space screens

A world-space screen does not support scaling, and the engine forces scale-mode back to "none" on one. Set screen-space alongside scale-mode="blend" for it to have any effect.

Example

A screen-space screen hosting a text element. With scale-mode="blend", the UI scales as the canvas resizes — try the fullscreen button to see it, or edit the text:

Live Example

<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/fonts/arial.json" type="font" id="arial"></pc-asset>
    <pc-scene>
        <pc-entity name="camera">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
        </pc-entity>
        <pc-entity name="ui">
            <!-- A 2D screen that scales with the canvas -->
            <pc-screen screen-space="true" scale-mode="blend" reference-resolution="640 320"></pc-screen>
            <!-- Text rendered on the parent screen -->
            <pc-entity name="title">
                <pc-element type="text" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                            font-asset="arial" font-size="48" color="#ff8a3c"
                            text="Hello, World!"></pc-element>
            </pc-entity>
        </pc-entity>
    </pc-scene>
</pc-app>

JavaScript Interface

You can programmatically create and manipulate <pc-screen> elements using the ScreenComponentElement API.

The component property is the engine ScreenComponent the element adds — null until the element is ready — and everything the attributes do not expose is available on it.

Attributes​

Example​

JavaScript Interface​

See Also​

Attributes

Example

JavaScript Interface

See Also