Importing images

Supported image formats

Godot can import the following image formats:

  • BMP (.bmp) - No support for 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported.

  • DirectDraw Surface (.dds) - If mipmaps are present in the texture, they will be loaded directly. This can be used to achieve effects using custom mipmaps.

  • OpenEXR (.exr) - Supports HDR (highly recommended for panorama skies).

  • Radiance HDR (.hdr) - Supports HDR (highly recommended for panorama skies).

  • JPEG (.jpg, .jpeg) - Doesn't support transparency per the format's limitations.

  • PNG (.png) - Precision is limited to 8 bits per channel upon importing (no HDR images).

  • Truevision Targa (.tga)

  • SVG (.svg) - SVGs are rasterized using ThorVG when importing them. Support is limited; complex vectors may not render correctly. You can check whether ThorVG can render a certain vector correctly using its web-based viewer. For complex vectors, rendering them to PNGs using Inkscape is often a better solution. This can be automated thanks to its command-line interface.

  • WebP (.webp) - WebP files support transparency and can be compressed lossily or losslessly. The precision is limited to 8 bits per channel.

Note

If you've compiled the Godot editor from source with specific modules disabled, some formats may not be available.

Importing textures

The default action in Godot is to import images as textures. Textures are stored in video memory. Their pixel data can't be accessed directly from the CPU without converting them back to an Image in a script. This is what makes drawing them efficient.

There are over a dozen import options that can be adjusted after selecting an image in the FileSystem dock:

Import options in the Import dock after selecting an image in the FileSystem dock

Import options in the Import dock after selecting an image in the FileSystem dock. Some of these options are only visible with certain compression modes.

Changing import type

It is possible to choose other types of imported resources in the Import dock:

  • BitMap: 1-bit monochrome texture (intended to be used as a click mask in TextureButton and TouchScreenButton). This resource type cannot be displayed directly onto 2D or 3D nodes, but the pixel values can be queried from a script using get_bit.

  • Cubemap: Import the texture as a 6-sided cubemap, with interpolation between the cubemap's sides (seamless cubemaps), which can be sampled in custom shaders.

  • CubemapArray: Import the texture as a collection of 6-sided cubemaps, which can be sampled in custom shaders. This resource type can only be displayed when using the Forward+ or Forward Mobile rendering methods, not Compatibility.

  • Font Data (Monospace Image Font): Import the image as a bitmap font where all characters have the same width. See Using Fonts.

  • Image: Import the image as-is. This resource type cannot be displayed directly onto 2D or 3D nodes, but the pixel values can be queried from a script using get_pixel.

  • Texture2D: Import the image as a 2-dimensional texture, suited for display on 2D and 3D surfaces. This is the default import mode.

  • Texture2DArray: Import the image as a collection of 2-dimensional textures. Texture2DArray is similar to a 3-dimensional texture, but without interpolation between layers. Built-in 2D and 3D shaders cannot display texture arrays, so you must create a custom shader in 2D or 3D to display a texture from a texture array.

  • Texture3D: Import the image as a 3-dimensional texture. This is not a 2D texture applied onto a 3D surface. Texture3D is similar to a texture array, but with interpolation between layers. Texture3D is typically used for FogMaterial density maps in volumetric fog, Environment 3D LUT color correction and custom shaders.

  • TextureAtlas: Import the image as an atlas of different textures. Can be used to reduce memory usage for animated 2D sprites. Only supported in 2D due to missing support in built-in 3D shaders.

Detect 3D

The default import options (no mipmaps and Lossless compression) are suited for 2D, but are not ideal for most 3D projects. Detect 3D makes Godot aware of when a texture is used in a 3D scene (such as a texture in a BaseMaterial3D). If this happens, several import options are changed so the texture flags are friendlier to 3D. Mipmaps are enabled and the compression mode is changed to VRAM Compressed unless Detect 3D > Compress To is changed. The texture is also reimported automatically.

A message is printed to the Output panel when a texture is detected to be used in 3D.

If you run into quality issues when a texture is detected to be used in 3D (e.g. for pixel art textures), change the Detect 3D > Compress To option before using the texture in 3D, or change Compress > Mode to Lossless after using the texture in 3D. This is preferable to disabling Detect 3D, as mipmap generation remains enabled to prevent textures from looking grainy at a distance.

Import options

See also

In Godot 4.0, changing the texture filter and repeat mode is no longer done in the import options.

Instead, texture filter and repeat modes are changed in the CanvasItem properties in 2D (with a project setting acting as a default), and in a per-material configuration in 3D. In custom shaders, filter and repeat mode is changed on the sampler2D uniform using hints described in the Shading language documentation.

Compress > Mode

Images are one of the largest assets in a game. To handle them efficiently, they need to be compressed. Godot offers several compression methods, depending on the use case.

  • Lossless: This is the default and most common compression mode for 2D assets. It shows assets without any kind of artifacting, and disk compression is decent. It will use considerably more amount of video memory than VRAM Compression, though. This is also the recommended setting for pixel art.

  • Lossy: This is a good choice for large 2D assets. It has some artifacts, but less than VRAM compression and the file size is several times lower compared to Lossless or VRAM Uncompressed. Video memory usage isn't decreased by this mode; it's the same as with Lossless or VRAM Uncompressed.

  • VRAM Compressed: This is the default and most common compression mode for 3D assets. Size on disk is reduced and video memory usage is also decreased considerably (usually by a factor between 4 and 6). This mode should be avoided for 2D as it exhibits noticeable artifacts, especially for lower-resolution textures.

  • VRAM Uncompressed: Only useful for formats that can't be compressed, such as raw floating-point images.

  • Basis Universal: This alternative VRAM compression mode encodes the texture to a format that can be transcoded to most GPU-compressed formats at load-time. This provides very small files that make use of VRAM compression, at the cost of lower quality compared to VRAM Compressed and slow compression times. VRAM usage is usually the same as VRAM Compressed. Basis Universal does not support floating-point image formats (the engine will internally fall back to VRAM Compressed instead).

Note

Even in 3D, "pixel art" textures should have VRAM compression disabled as it will negatively affect their appearance, without improving performance significantly due to their low resolution.

In this table, each of the 5 options are described together with their advantages and disadvantages (good = best, bad = worst):

Compress mode

Lossless

Lossy

VRAM Compressed

VRAM Uncompressed

Basis Universal

Description

Stored as Lossless WebP / PNG

Stored as Lossy WebP

Stored as S3TC, BPTC or ETC2 depending on platform

Stored as raw pixels

Transcoded to VRAM Compressed format

Size on disk

regular Small

good Very small

regular Small

bad Large

good Very small

Memory usage

bad Large

bad Large

good Small

bad Large

good Small

Performance

regular Normal

regular Normal

good Fast

regular Normal

good Fast

Quality loss

good None

regular Slight

bad Moderate

good None

bad Moderate

Load time

bad Slow

bad Slow

good Fast

regular Normal

regular Normal

Estimated memory usage for a single RGBA8 texture with mipmaps enabled:

Texture size

Lossless

Lossy

<