Textures and Terrain Materials

What the terrain texture library is#

Terrain is painted with terrain textures: tiling ground materials such as grass, rock, sand or snow. Each has an albedo (colour) image and, optionally, a normal map, plus tiling and shading settings. They live in one texture library per project, stored at assets/textures/texture_library.res, and every map picks the textures it paints with from that library.

A new project's library is seeded from the editor's bundled starter library the first time it is used, so you can paint immediately; add your own textures as your game's look takes shape. The library can hold up to 32 textures, and each map can use up to 32 of them.

The same library is shown in two places:

• The Assets tab's Terrain Textures category: a folder browser for organizing, renaming, sharing and deleting textures, with a preview panel that tells you which maps use each one.
• The Map Editor's Textures tab (right panel, Terrain mode), whose bottom Texture Library panel is where you add textures to the open map.

This is different from the Assets tab's Textures category, which lists generic Godot texture resources (.tres / .res) and has nothing to do with terrain. Sprites and icons are covered under Asset Manager.

Import a terrain texture#

Quick import (albedo only)#

1. Open the Assets tab and select Terrain Textures. Navigate into the folder you want the texture filed under.
2. Click Import and pick image files (.png, .jpg, .jpeg, .webp, .bmp, .tga, .exr, .dds), or drag the images from your file manager onto the grid.

Each image becomes a texture named after its file, with the image as albedo and no normal map. Tiling (UV Scale) starts at 1.0.

Full import with a normal map or a PBR set#

1. In the Map Editor, open a map, switch to Terrain mode and select the Textures tab on the right. The Texture Library panel appears at the bottom of the right panel.
2. Click + Add Texture. The Add Texture dialog opens with a Name field and two slots, Albedo and Normal (optional).
3. Drag an image onto a slot, or click a slot to browse. A single file whose name identifies it as a normal map goes to the Normal slot automatically; anything else goes to Albedo. The name is filled from the albedo file if you have not typed one.
4. Click Add Texture. The texture joins the library in the folder you are browsing. Maps that already use a library texture keep their own copy, so deleting or editing a library entry later does not change them.

Dropping several files at once treats them as a PBR set. Files are classified by name and channel-packed the way the terrain shader expects:

A green Packed set line in the dialog reports what was packed (for example "height → albedo alpha; roughness → normal alpha; DirectX normal → OpenGL") and which files were skipped. If no file name is recognizable, the first file becomes the albedo and the second the normal.

Signed-in uploads#

New library textures are also published to your cloud library as texture assets (de-duplicated by content), and the card gains a cloud badge once the upload lands. In the Assets tab, a texture's right-click menu shows Upload to Cloud, Uploading to Cloud... or On Cloud accordingly. See Cloud library.

Quality tiers: what is stored on disk#

The library does not keep your original image. On import, each channel is resized to the quality tiers maps can use, 128, 256 and 1024 pixels, and only those files are written, under assets/textures/files/<key>/ as albedo_128.res, albedo_256.res, albedo_1024.res (and normal_* when a normal map is present). The library entry points at the largest tier.

The source size decides the top tier: it snaps to the nearest tier, so a 512-pixel source tops out at 256, a 700-pixel source at 1024, a 64-pixel source at 128, and a 2048- or 4096-pixel source at 1024. Every tier at or below the top is generated. Nothing above 1024 is kept, because 1024 is the highest quality a map can select and a raw 4K image is dead weight on disk.

Clean unused texture files#

Deleting textures, switching quality and replacing images can leave .res files that nothing references. In the Map Editor's Texture Library panel click Clean Unused and confirm Delete Unused; the editor deletes every file under assets/textures/files/ that no map or the library references and reports how many files it removed and kept. Deleting a texture from the Assets tab runs the same cleanup automatically.

Per-map texture quality#

All textures on one map are built into a single texture array, which requires every entry to have the same size and format. Instead of asking you to match sizes by hand, each map has a Quality setting and resamples every texture it uses to that size.

1. Open the map, select the Textures tab in Terrain mode.
2. In the footer of the Map Textures list, set Quality to Low (128 px), Medium (256 px) or High (1024 px). New maps default to High.
3. The map's textures are re-normalized immediately for preview, the map is marked modified, and the setting is saved with the map scene.

Pick Low or Medium for large maps, stylized games or low-end targets; the saving is real because a 1024-pixel texture set is 64 times the pixels of a 128-pixel one. The library itself is unaffected; other maps keep their own quality.

Browse and organize#

The Terrain Textures category in the Assets tab mirrors the Models browser:

• All Textures / Recent chips switch between the folder tree and a flat newest-first list.
• New Folder creates a folder at the current location; folders are stored inside the library file, so organizing never moves image files. Right-click a folder for Open, New Subfolder, Rename Folder, Delete Folder (its textures move up to the parent).
• Cards show a material-ball preview: the texture rendered on a lit sphere with its normal map applied, the same render the cloud library uses for texture thumbnails. Previews are rendered on demand and cached for the session.
• Select with click, Ctrl-click and Shift-click; drag a selection onto a folder tile to move it. Right-click a texture for Edit Defaults..., the cloud row, Rename, Move to Root and Delete, or Upload N to Cloud, Move N to Root and Delete N Textures for a selection.
• The preview panel shows the sphere render, Type: Terrain Texture, the albedo size, whether a normal map is present, the folder, the cloud status and a Used by maps list of every map whose scene references the texture.

The Map Editor's Texture Library panel has the same folders, a Search textures... box, a size slider, a count label, and sorts textures by resolution (largest first). Its right-click menu adds Add to Map and names the delete action Delete from Library. A card with a size badge means the texture's size differs from the open map's first texture; it can still be added, since the map resamples it.

Use a texture on a map#

1. With a map open, select the Textures tab in Terrain mode.
2. Drag a card from the Texture Library panel onto the Map Textures list, or right-click the card and choose Add to Map. The map receives its own copy of the texture's settings, sharing the image files.
3. Select the slot in Map Textures and paint. See Terrain for the brushes.

To remove a slot from a map, delete it from the Map Textures list; the Delete Texture dialog offers Delete & Shift (later slots move down and painted areas repaint accordingly) or Keep Slot (Blank) (a blank placeholder keeps painted areas on their slot so you can drop a replacement onto it later).

Texture defaults#

Edit Defaults... (Assets tab, or the Map Editor's library menu) opens the texture editor for a library texture. These values are copied into a map when the texture is added, so edit them before adding, or edit the map's own copy afterwards.

Click OK to apply or Cancel to discard.

Files on disk#

Everything here ships in the game's content pack. Texture files that no map or the library references are safe to remove with Clean Unused.

With AI (MCP)#

An assistant paints terrain materials rather than managing the library: paint_terrain_material assigns a surface material (grass, rock, sand, snow, dirt or water) wherever a height, slope or region selector matches, driving the control map that bake_terrain turns into a real terrain, and a generate_terrain op stack with a biome op assigns materials automatically from elevation, moisture and slope. See the Tools reference.