Texture2D

A GPU texture for the 2D engine — the image behind a Sprite or Tilemap. The raw file bytes are decoded and uploaded natively. Not interchangeable with the 3D Texture (material images).

At a glance

const tex = await Texture2D.load(asset('./hero.png'))
const hero = new Sprite({ texture: tex })
console.log(tex.width, tex.height)      // pixel dimensions

Loading

Texture2D.load(source: string | FetchResponse | File): Promise<Texture2D>

• URL string — an asset('./file.png') path or a remote https://… URL; fetched, then decoded. Rejects on HTTP status ≥ 400 or a decode failure.
• FetchResponse — an already-fetched response (skip the extra request).
• File — e.g. from Canvas.toFile() or openFilePicker.

Texture2D.fromCanvas(canvas: Canvas): Texture2D

Wraps a Canvas's baked surface as a texture — synchronous (already rasterized, no decode). Its width/height are the canvas's physical pixels (logical size × pixelRatio). Assigning a Canvas directly to sprite.texture does this for you.

Properties & lifecycle

tex.width, tex.height    // pixels (readonly)
tex.id                   // native texture handle (readonly)
tex.destroy(): void      // free the GPU texture

Textures are shared freely — many sprites can use one Texture2D. destroy() frees the GPU resource; sprites still referencing it are undefined behavior.

See also

• Sprite — using a texture, frames/atlases
• Tilemap — atlas grids
• SpriteAnimation — sheet slicing into clips
• Scene2D — the global filter setting