<pc-asset>

<pc-asset> 声明模型、纹理、字体、声音、脚本或 JSON 等资源，通过 id 供其他标签引用。

用法

必须直接位于 <pc-app> 下。

属性

属性	类型	默认值	说明
`address-u`	Enum	`"repeat"`	texture 和 textureatlas 的水平越界采样：repeat、clamp 或 mirror
`address-v`	Enum	`"repeat"`	texture 和 textureatlas 的垂直越界采样：repeat、clamp 或 mirror
`anisotropy`	Number	`"1"`	纹理最大各向异性级别，改善倾斜角度质量
`atlas`	资源 ID	-	sprite 使用的 textureatlas id，图集必须先声明
`data`	String	-	内联 JSON 数据，用于图集帧定义和精灵
`flip-y`	Boolean	`"false"`	纹理上传是否上下翻转。引擎使用 ImageBitmap 时不生效，始终非翻转：WebGPU 始终如此，WebGL 2 除 Safari 外也如此
`frame-keys`	String	-	精灵帧键列表，空格或逗号分隔
`id`	String	-	供其他标签引用的唯一 ID
`lazy`	Boolean	`"false"`	是否跳过预加载。首次被标签按 id 引用，或移除 lazy 后才下载
`mag-filter`	Enum	`"linear"`	纹理放大滤波：nearest 或 linear
`min-filter`	Enum	`"linear-mip-linear"`	纹理缩小滤波：nearest、linear、nearest-mip-nearest、linear-mip-nearest、nearest-mip-linear 或 linear-mip-linear
`mipmaps`	Boolean	`"true"`	纹理是否生成和使用 mipmap
`pixels-per-unit`	Number	`"1"`	精灵每世界单位像素数
`render-mode`	Enum	`"simple"`	精灵模式：simple、sliced 或 tiled，九宫格面板使用 sliced
`src`	String	-	资源文件路径
`srgb`	Boolean	`"false"`	纹理是否保存 sRGB 伽马编码颜色，启用硬件解码
`type`	Enum	自动推断	animation、animclip、audio、binary、css、container、font、gsplat、html、json、script、shader、sprite、text、texture 或 textureatlas。animation 与 animclip 为 `<pc-anim-clip>` 提供轨道

读取时机

lazy 和纹理选项实时生效，移除恢复表中默认值。其余属性仅在资源创建时读取，之后修改无效。

为不适用类型设置属性，例如音频设置纹理选项，或非精灵设置 frame-keys，会警告并列出忽略项。

纹理选项

创建纹理时，各属性覆盖 data JSON 对应键。未设置时不写入，保留按格式的默认值，例如 HDR 的 rgbe 编码或 KTX2 转码格式，因此仅设置确实需要的项。

已加载纹理也可实时修改，适合开发者工具试验。srgb 和 mipmaps 会重建 GPU 资源，开销较高，应尽量预先声明。移除属性会恢复表中默认，不一定等于文件加载时默认，例如 HDR 原本 nearest，移除 mag-filter 后变为 linear。

<!-- Crisp pixel-art texture: no filtering, no mipmaps, clamped at the edges -->
<pc-asset id="sprite-sheet" src="assets/textures/tiles.png"
          min-filter="nearest" mag-filter="nearest" mipmaps="false"
          address-u="clamp" address-v="clamp"></pc-asset>

<!-- Tiling ground texture, sharp at grazing angles -->
<pc-asset id="ground" src="assets/textures/gravel.jpg" anisotropy="16"></pc-asset>

类型推断

省略 type 时，按 src 扩展名推断：

类型	扩展名
`audio`	`.mp3`
`binary`	`.bin`
`container`	`.glb`, `.gltf`
`css`	`.css`
`gsplat`	`.lcc2`, `.ply`, `.sog`
`html`	`.html`
`json`	`.json`
`script`	`.js`, `.mjs`
`shader`	`.frag`, `.glsl`, `.vert`
`text`	`.txt`
`texture`	`.hdr`, `.jpg`, `.ktx2`, `.png`, `.webp`

其他扩展名，以及 font、sprite、textureatlas 等类型必须显式设置 type。src 也必须以表内小写扩展名结尾；带查询参数、片段、大写 .JPG 或其他拼法 .jpeg 都不能推断。不指定会警告 Unsupported asset type，且不创建资源。

事件

通过 addEventListener() 或 oneventname property 监听。

事件	说明
`load`	每次加载完成触发，包括延迟资源及后续重新加载
`error`	加载失败时触发 `ErrorEvent`，message 为引擎错误

两者都不冒泡，应监听元素，或在 pc-app 捕获全部资源事件。捕获监听还会收到模型、WASM 和应用自身 error，因此应检查目标：

document.querySelector('pc-app').addEventListener('error', (event) => {
    if (event.target.localName === 'pc-asset') {
        console.warn(`${event.target.id} failed to load: ${event.message}`);
    }
}, true);

就绪是独立信号，表示达到标记声明的状态。预加载资源需等待成功或失败，失败仍就绪；lazy 注册即就绪；运行时插入也在资源创建时就绪，加载可能仍进行。非直接 pc-app 子项或类型不支持时警告，永不就绪。

示例

两个资源：从 CDN 加载的引擎辅助脚本和 GLB。脚本按名注册，模型按 id 引用。拖动可环绕：

实时示例

<pc-app>
    <!-- Script asset: type inferred from the .mjs extension -->
    <pc-asset src="https://cdn.jsdelivr.net/npm/[email protected]/scripts/esm/camera-controls.mjs"></pc-asset>
    <!-- Container asset: type inferred from the .glb extension -->
    <pc-asset src="https://developer.playcanvas.com/assets/playcanvas-cube.glb" id="cube"></pc-asset>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
            <pc-script>
                <pc-script-instance name="cameraControls" enable-pan="false" zoom-range="1.5 6"></pc-script-instance>
            </pc-script>
        </pc-entity>
        <pc-entity name="light" rotation="45 30 0">
            <pc-light intensity="2"></pc-light>
        </pc-entity>
        <pc-model asset="cube"></pc-model>
    </pc-scene>
</pc-app>

精灵由定义帧的纹理图集，以及一个或多个引用图集的 sprite 资源组成，图集必须先声明：

<pc-app>
    <!-- Texture atlas, with inline frame definitions -->
    <pc-asset id="ui-sheet" type="textureatlas" src="assets/textures/ui.png"
              data='{"frames":{"3":{"name":"panel","border":[10,10,10,10],"rect":[41,1,100,100],"pivot":[0.5,0.5]}}}'></pc-asset>
    <!-- 9-sliced sprite that reads frame "3" from the atlas -->
    <pc-asset id="panel" type="sprite" atlas="ui-sheet" frame-keys="3" render-mode="sliced"></pc-asset>
</pc-app>

JavaScript 接口

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

asset 是已注册的底层 Asset，就绪前为 null，也可通过 AssetElement.get(id) 查询，无需持有元素。

另请参阅

<pc-model>：实例化容器。
<pc-material>：使用纹理贴图。
<pc-sound-slot>：播放音频。
<pc-script-instance>：运行脚本资源。

示例：GLB 加载器、视频纹理和基础声音。

属性​

纹理选项​

类型推断​

事件​

示例​

JavaScript 接口​

另请参阅​

属性

纹理选项

类型推断

事件

示例

JavaScript 接口

另请参阅