<pc-app>

<pc-app> 是应用根，初始化 PlayCanvas 并容纳场景。

用法

必须位于文档 body 内。

属性

属性	类型	默认值	说明
`alpha`	Boolean	`"true"`	是否为帧缓冲分配 Alpha，使页面从未绘制区透出
`antialias`	Boolean	`"true"`	是否抗锯齿
`area-light-luts`	资源 ID	-	面光源查找表 JSON 资源 ID，加载为全应用启用，清空关闭，立即生效，详见面光源
`backend`	Enum	`"webgpu"`	webgpu、webgl2 或 null。WebGPU 不可用自动回退，可强制 WebGL 2；null 不绘制，用于无界面测试
`depth-buffer`	Boolean	`"true"`	是否分配深度缓冲
`devtools`	Boolean	`"true"`	是否向 Inspector 等开发工具公开应用，生产可关闭，但不是安全屏障，页面仍可访问 app
`loading-bar`	Boolean	`"true"`	启动和预加载时是否显示内置加载条
`max-pixel-ratio`	Number	不限制	大于 0 的像素比上限，实际取设备比与上限较小者。1 为 CSS 分辨率，2 可兼顾清晰度和开销
`physics-time-scale`	Number	`"1"`	在 time-scale 之上再缩放物理时间，0 仅暂停物理，其他逻辑继续，适合暂停菜单
`picking`	Enum	`"auto"`	auto 仅有实体或场景监听器时拾取；always 支持文档或框架委托等不可见监听；none 不拾取。拾取要再次渲染，详见事件分发
`stencil-buffer`	Boolean	`"true"`	是否分配模板缓冲
`time-scale`	Number	`"1"`	应用时间倍率，脚本、动画、物理同时缩放。0 冻结时间但仍渲染，update 与 postUpdate 仍以 dt=0 执行，未乘 dt 的逻辑继续，游戏应自行检查暂停。仅物理暂停用 physics-time-scale
`with-credentials`	Boolean	`"false"`	跨域资源请求是否携带 Cookie 和 HTTP 凭据，需服务器允许 CORS。客户端状态全页面共享，任一应用修改会影响全部应用

读取时机

alpha、antialias、backend、depth-buffer、stencil-buffer 配置图形设备， devtools 配置应用，均在元素插入文档并启动时读取一次。之后修改仅更新元素 property，不改变运行应用，并输出警告。要应用新值，需移除元素再重新插入。

其他属性均实时生效，但 loading-bar 运行时只能移除，不能重新显示，详见加载条。两种时间缩放都在脚本 initialize() 前应用。

尺寸

元素像 video 或 img 一样作为 CSS 控制的块级盒，默认采用画布固有的 300×150 像素。画布始终填满元素，绘制缓冲区实时跟随尺寸，并受 max-pixel-ratio 限制。无论分栏拖动、Flex 重排还是 CSS 动画，渲染场景都会跟随。

填满视口由普通 CSS 完成，并非内置行为：

pc-app {
    width: 100%;
    height: 100vh;  /* fallback for browsers without dynamic viewport units */
    height: 100dvh;
}

也可嵌入卡片、分栏或网格中，采用任意尺寸，同页可以并存多个应用。

显式指定尺寸

请显式设置 width 和 height。默认样式已有具体尺寸，优先于 inset 拉伸，因此仅 position:fixed; inset:0 不会填满视口。默认值通过 :where() 以零权重声明，任何页面规则都可覆盖。

缓冲区同时跟随显示器变化。窗口移动到不同像素密度屏幕，或缩放页面时，即使元素尺寸不变，应用也会重新评估设备像素比并调整缓冲区。有效比率为上限与设备比的较小值，保存在 app.graphicsDevice.maxPixelRatio；元素 maxPixelRatio 返回配置上限。代码也可直接指定图形设备比率，之后设备变化只调整缓冲尺寸而保留该比率，直到重新设置 max-pixel-ratio，才由元素重新接管。

XR 呈现期间是例外，此时缓冲区由 XR 会话管理。

加载条

启动和预加载时，元素顶部显示加载条。 loading-bar=false 可隐藏，启动后修改会立即移除；重新设 true 不恢复，直到重新插入。也可通过以下 CSS 自定义属性调整外观：

属性	说明
`--pc-loading-bar-color`	已填充部分颜色
`--pc-loading-bar-background`	未填充轨道颜色
`--pc-loading-bar-height`	加载条高度

自定义加载画面时，隐藏内置条，再用 progress 事件和 loadProgress property 驱动。

事件

通过 addEventListener() 或 oneventname property 监听。

事件	说明
`progress`	预加载触发 `ProgressEvent`，loaded 和 total 为资源数而非字节，失败也计已加载。每次启动至少一次，末次两者相等
`error`	无法创建图形设备时触发 `ErrorEvent`，例如禁用 WebGL 或 GPU 黑名单。message 列出后端，error 包含底层失败，详见下文

两者不冒泡，应直接监听元素。

处理启动失败

触发 error 后不会就绪，app 保持 null， whenReady(pc-app) 也不结束，详见代码访问。需要回退界面时应监听事件，不要只等待。建议用内联属性，因为库启动时就可能失败，自己的模块尚未执行，后注册监听可能错过。内联属性在元素解析时已经存在：

<pc-app onerror="document.getElementById('fallback').hidden = false">

事件覆盖完全无法创建设备的情况。默认 backend 下，浏览器先试 WebGPU，再回退 WebGL 2，若两者都失败，当前引擎某些路径会保持等待而不触发 error。必须显示回退时，可再设置数秒未就绪的超时。

移除再插入元素会按当前属性重试启动。

实体指针事件也冒泡到应用，与画布原生事件并存。isTrusted=true 为原生，false 为分发，是否分发取决于 picking，详见事件分发。

示例

摄像机、灯光和球体构成完整应用。可设置 antialias=false 或 max-pixel-ratio=1 比较：

实时示例

<pc-app>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera clear-color="#8099e6"></pc-camera>
        </pc-entity>
        <pc-entity name="light" rotation="45 45 0">
            <pc-light></pc-light>
        </pc-entity>
        <pc-entity name="ball">
            <pc-render type="sphere"></pc-render>
        </pc-entity>
    </pc-scene>
</pc-app>

JavaScript 接口

可以通过 AppElement API创建和操作元素。

app 是底层 AppBase，就绪前为 null，可访问场景、资源注册表和循环；elementFromEntity() 将实体映射回元素。

另请参阅

<pc-scene>：场景。
<pc-asset>：预加载资源。
<pc-wasm>：启动前加载模块。
代码访问：等待就绪并访问应用。

示例：旋转立方体和基本形状。

属性​

尺寸​

加载条​

事件​

处理启动失败​

示例​

JavaScript 接口​

另请参阅​

属性

尺寸

加载条

事件

处理启动失败

示例

JavaScript 接口

另请参阅