godotengine · mhilbrunner · Feb 27, 2023 · Feb 11, 2023
diff --git a/tutorials/3d/3d_rendering_limitations.rst b/tutorials/3d/3d_rendering_limitations.rst
@@ -23,6 +23,11 @@ your texture to display correctly on all platforms, you should avoid using
 textures larger than 4096×4096 and use a power of two size if the texture needs
 to repeat.
 
+To limit the size of a specific texture that may be too large to render, you can
+set the **Process > Size Limit** import option to a value greater than ``0``.
+This will reduce the texture's dimensions on import (preserving aspect ratio)
+without affecting the source file.
+
 .. _doc_3d_rendering_limitations_color_banding:
 
 Color banding

diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst
@@ -448,6 +448,8 @@ World Triplanar
 When using triplanar mapping, it is computed in object local space. This
 option makes it use world space instead.
 
+.. _doc_standard_material_3d_sampling:
+
 Sampling
 --------
 

diff --git a/tutorials/3d/volumetric_fog.rst b/tutorials/3d/volumetric_fog.rst
@@ -204,6 +204,8 @@ the following properties in FogMaterial:
   of the FogVolume. This can be used to vary fog density within the FogVolume
   with any kind of static pattern. For animated effects, consider using a custom
   :ref:`fog shader <doc_fog_shader>`.
+  You can import any image as a 3D texture by
+  :ref:`changing its import type in the Import dock <doc_importing_images_changing_import_type>`.
 
 Custom FogVolume shaders
 ------------------------

diff --git a/tutorials/assets_pipeline/img/asset_workflow1.png b/tutorials/assets_pipeline/img/asset_workflow1.png
diff --git a/tutorials/assets_pipeline/img/asset_workflow2.png b/tutorials/assets_pipeline/img/asset_workflow2.png
diff --git a/tutorials/assets_pipeline/img/asset_workflow3.png b/tutorials/assets_pipeline/img/asset_workflow3.png
diff --git a/tutorials/assets_pipeline/img/asset_workflow4.png b/tutorials/assets_pipeline/img/asset_workflow4.png
diff --git a/tutorials/assets_pipeline/img/asset_workflow5.png b/tutorials/assets_pipeline/img/asset_workflow5.png
diff --git a/tutorials/assets_pipeline/img/import_process_change_preset.webp b/tutorials/assets_pipeline/img/import_process_change_preset.webp
diff --git a/tutorials/assets_pipeline/img/import_process_changing_import_type.webp b/tutorials/assets_pipeline/img/import_process_changing_import_type.webp
diff --git a/tutorials/assets_pipeline/img/import_process_example.webp b/tutorials/assets_pipeline/img/import_process_example.webp
diff --git a/tutorials/assets_pipeline/img/import_process_import_defaults.webp b/tutorials/assets_pipeline/img/import_process_import_defaults.webp
diff --git a/tutorials/assets_pipeline/img/importing_audio_samples_advanced_import_settings.webp b/tutorials/assets_pipeline/img/importing_audio_samples_advanced_import_settings.webp
diff --git a/tutorials/assets_pipeline/img/importing_audio_samples_import_options_mp3.webp b/tutorials/assets_pipeline/img/importing_audio_samples_import_options_mp3.webp
diff --git a/tutorials/assets_pipeline/img/importing_audio_samples_import_options_wav.webp b/tutorials/assets_pipeline/img/importing_audio_samples_import_options_wav.webp
diff --git a/tutorials/assets_pipeline/img/importing_images_import_dock.webp b/tutorials/assets_pipeline/img/importing_images_import_dock.webp
diff --git a/tutorials/assets_pipeline/img/importing_images_inspector_preview.webp b/tutorials/assets_pipeline/img/importing_images_inspector_preview.webp
diff --git a/tutorials/assets_pipeline/img/importing_images_normal_map_rgtc.webp b/tutorials/assets_pipeline/img/importing_images_normal_map_rgtc.webp
diff --git a/tutorials/assets_pipeline/import_process.rst b/tutorials/assets_pipeline/import_process.rst
@@ -3,40 +3,48 @@
 Import process
 ==============
 
-Importing assets in Godot 3.0+
-------------------------------
+Importing assets in Godot
+-------------------------
 
-Previously, importing assets in Godot 2.x required manual maintenance
-of a separate directory with source assets. Without doing this, it was
-impossible to specify how to convert and change import flags for
-textures, audio files, scenes, etc.
+To import assets in Godot, place your assets (image files, scenes, audio
+files, fonts, etc) directly in the project folder. There are 2 ways to achieve this:
 
-In Godot 3.0+, we use a more modern approach to importing: Simply drop
-your assets (image files, scenes, audio files, fonts, etc) directly in the
-project folder (copy them manually with your OS file explorer).
-Godot will automatically import these files internally
-and keep the imported resources hidden in a ``res://.import`` folder.
+- **For any file type:** Copy files manually with your operating system's file manager.
+- **For file types that can be imported by Godot:**
+  Drag-and-drop files from the operating system's file manager to the editor's FileSystem dock.
+  This only works with *resource* file types (i.e. file types that Godot can import).
 
-This means that when trying to access imported assets through code you
+Godot will automatically import these files internally and keep the imported
+resources hidden in a ``res://.godot/imported/`` folder.
+
+This means that when trying to access imported assets through code, you
 need to use the :ref:`Resource Loader<class_ResourceLoader>` as it will
 automatically take into account where the internal files are saved. If you
-try and access an imported asset using the :ref:`FileAccess <class_FileAccess>` class
-it will work in the editor, but break in the exported project.
+try and access an imported asset using the :ref:`FileAccess <class_FileAccess>` class,
+it will work in the editor, but **it will break in the exported project**.
 
 However, the :ref:`Resource Loader<class_ResourceLoader>` cannot access
-non imported files, only the :ref:`FileAccess <class_FileAccess>` class can.
+non-imported files. Only the :ref:`FileAccess <class_FileAccess>` class can.
 
 Changing import parameters
 --------------------------
 
-To change the import parameters of an asset in Godot (again, keep in mind
-import parameters are only present in non-native Godot resource types)
-select the relevant resource in the filesystem dock:
+.. note::
+
+    Import parameters are only present in *non-native* Godot resource types.
+    This means Godot's own scene and resource file formats (``.tscn``, ``.scn``,
+    ``.tres``, ``.res``) don't have import options you can select in the Import
+    dock.
+
+To change the import parameters of an asset in Godot, select the relevant
+resource in the FileSystem dock:
 
-.. image:: img/asset_workflow1.png
+.. image:: img/import_process_example.webp
 
-Then, after adjusting the parameters, press "Reimport". These parameters
-will only be used for this asset and on future reimports.
+After adjusting the parameters, click **Reimport**. Be careful: if you select
+another file in the FileSystem dock before clicking **Reimport**, changes will
+be discarded. After clicking **Reimport**, the chosen parameters will only be
+used for this asset and on future reimports.
 
 Changing the import parameters of several assets at the same time is also
 possible. Simply select all of them together in the resources dock and the
@@ -66,48 +74,77 @@ automatic reimport of it, applying the preset configured for that specific
 asset.
 
 Files generated
------------------
+---------------
+
+Importing will add an extra ``<asset>.import`` file next to the source file,
+containing the import configuration.
+
+**Make sure to commit these files to your version control system**, as these
+files contain important metadata.
+
+::
 
-Importing will add an extra ``<asset>.import`` file, containing the import
-configuration. Make sure to commit these to your version control system!
+    $ ls
+    example.png
+    example.png.import
+    project.godot
 
-.. image:: img/asset_workflow4.png
+Additionally, extra assets will be present in the hidden
+``res://.godot/imported/`` folder:
 
-Additionally, extra assets will be preset in the hidden ``res://.import`` folder:
+::
 
-.. image:: img/asset_workflow5.png
+    $ ls .godot/imported
+    example.png-218a8f2b3041327d8a5756f3a245f83b.ctex
+    example.png-218a8f2b3041327d8a5756f3a245f83b.md5
 
 If any of the files present in this folder is erased (or the whole folder), the
-asset or assets will be reimported automatically. As such, committing this folder
-to the version control system is optional. It can shorten
-reimporting time when checking out on another computer, but it takes considerably
-more space and transfer time. Pick your poison!
+asset or assets will be reimported automatically. As such, committing the
+``.godot/`` folder to the version control system is not recommended. While
+committing this folder can shorten reimporting time when checking out on another
+computer, it requires considerably more space and bandwidth.
+
+The default version control metadata that can be generated on project creation
+will automatically ignore the ``.godot/`` folder.
 
 Changing import resource type
 -----------------------------
 
-Some source assets can be imported as different types of resources.
-For this, select the relevant type of resource desired and
-press "Reimport":
+Some source assets can be imported as different types of resources. For this,
+select the relevant type of resource desired then click **Reimport**:
+
+.. image:: img/import_process_changing_import_type.webp
 
-.. image:: img/asset_workflow2.png
+.. note::
 
+    For technical reasons, the editor must be restarted after changing an import
+    type in the Import dock.
 
 Changing default import parameters
------------------------------------
+----------------------------------
 
-Different types of games might require different defaults.
-Changing the defaults per project can be achieved by using the
-"Preset.." Menu. Besides some resource types offering presets,
-the default setting can be saved and cleared too:
+Different types of projects might require different defaults. Changing the import
+options to a predefined set of options can be achieved by using the
+**Preset...** Menu. Besides some resource types offering presets, the default
+settings can be saved and cleared too:
 
-.. image:: img/asset_workflow3.png
+.. image:: img/import_process_change_preset.webp
 
-Simplicity is key!
-------------------
+The default import parameters for a given resource type can be changed
+project-wide using the **Import Defaults** tab of the Project Settings dialog:
+
+.. image:: img/import_process_import_defaults.webp
+
+Further reading
+---------------
+
+This workflow takes a little time to get used to, but it enforces a more correct
+way to deal with resources.
 
-This workflow is aimed to be simple and take very little time to get used to. It also enforces a more
-correct way to deal with resources.
+There are many types of assets available for import. Continue reading to
+understand how to work with all of them:
 
-There are many types of assets available for import, so please continue reading to understand how to work
-with all of them!
+- :ref:`doc_importing_images`
+- :ref:`doc_importing_audio_samples`
+- :ref:`doc_importing_3d_scenes`
+- :ref:`doc_importing_translations`