godot-docs/tutorials/shaders/shader_materials.rst

.. _doc_shader_materials:

Shader materials
================

Introduction
------------

For the most common cases, Godot provides ready to use materials for
most types of shaders, such as :ref:`StandardMaterial3D <class_StandardMaterial3D>`,
:ref:`CanvasItemMaterial <class_CanvasItemMaterial>` and :ref:`ParticleProcessMaterial <class_ParticleProcessMaterial>`.
They are flexible implementations that cover most use cases.

Shader materials allow writing a custom shader directly, for maximum flexibility.
Examples of this are:

-  Create procedural textures.
-  Create complex texture blending effects.
-  Create animated materials, or materials that change over time.
-  Create refractive effects or other advanced effects.
-  Create special lighting shaders for more exotic materials.
-  Animate vertices, like tree leaves or grass.
-  Create custom particle code.
-  And much more!

Godot provides built in functionality to make frequent operations
easier. Additionally, Godot's shader editor will detect errors as you
type, so you can see your edited shaders in real-time. It is also
possible to edit shaders using a visual, node-based graph editor.

Creating a ShaderMaterial
-------------------------

Create a new ShaderMaterial in some object of your choice. Go to the
"Material" property and create a ShaderMaterial.

.. image:: img/shader_material_create.png

Next, click on the shader material to see its properties. From here you
can create a shader or visual shader. Regular shaders use code to set
their properties while a visual shader uses a node based workflow.

If you need to you can convert a visual shader to a text shader.
However you can't convert a text shader to a visual shader.

Choose one of them and you can start editing your shader.

.. image:: img/shader_create.png

If you create a regular shader click on it and the shader editor will open.

.. image:: img/shader_material_editor.png

If you create a visual shader the visual shader editor will open automatically.

.. image:: img/visual_shader_editor.png

In the visual shader editor you can click a button and see what your visual
shader looks like as shader code. This can be useful if you're trying to
replicate a text shader as nodes, or it can be used as a preview for converting
your visual shader to a text shader.

.. image:: img/visual_shader_code.png

.. note::

   To learn more about visual shaders, read :ref:`doc_visual_shaders`.

Converting to ShaderMaterial
----------------------------

It is possible to convert from StandardMaterial3D, CanvasItemMaterial and
ParticleProcessMaterial to ShaderMaterial. To do so, go to the material properties
and select the convert option.

.. image:: img/shader_material_convert.png

.. note::

   Using the convert option will turn the StandardMaterial3D into a ShaderMaterial
   with a text shader, not a visual shader.