Tutorial ‐ Creating a custom material

In this tutorial, you will be instructed on how to create brand new Material the Engine can render with a custom Shader Pipeline.

The Shader Pipeline

From here on out, a "Shader Pipeline" will simply refer to a linking of 2 or 3 specific shaders: The Vertex and Fragment shader, and optionally, the Geometry shader. For the purposes of this tutorial, the Geometry shader will not be used. The Vertex and Fragment shader are always required for a valid Shader Pipeline. Pipelines are stored in the resources/shaders directory, as .shp JSON files.

In order to create a new Pipeline, open the "Shaders" tool in your "Tools" tab:

Enter a memorable name into the "New Blank Pipeline" entry box, and hit "Create":

Select your new Pipeline from the list, and you will be presented with the following set of options:

The Shader Code

First, let's write some Vertex Shader code. Before that, we need to create a new vertex shader. Click on the Scripts tab in the Explorer window on the right of your screen:

Right-click on the empty space, and click "Focus parent". Then, create your vertex and fragment shaders files in the shaders directory, I will name mine awesome.vert and awesome.frag respectively:

Double-click your vertex shader file to open it in the built-in Text Editor, and copy the following code into the window:

#version 460 core

layout (location = 0) in vec3 VertexPosition;
layout (location = 1) in vec3 VertexNormal;

uniform mat4 RenderMatrix;
uniform mat4 Transform;

out vec3 Frag_VertexNormal;

void main()
{
  vec4 worldPosition = Transform * vec4(VertexPosition, 1.f);
  Frag_VertexNormal = VertexNormal;
  
  gl_Position = RenderMatrix * worldPosition;
}

Now, double-click your fragment shader and copy the following code into it:

#version 460 core

in vec3 Frag_VertexNormal;

out vec4 FragColor;

void main()
{
  vec3 colorTint = Frag_VertexNormal * .5f + .5f;
  FragColor = vec4(colorTint, 1.f);
}

Go back to the Shader Pipelines widget, and hit the ... button next to the Vertex Shader hyperlink:

In the opened Dialog, find and select your newly-created Vertex Shader. Do the same for the fragment shader:

Then, scroll to the bottom of the Shader Pipelines widget, and Save & Reload.

The Material

A Material is simply a set of textures and a Shader Pipeline, that, at a high-level, describes how something looks in the Engine. To create a Material, we should use the "Materials" window:

To create your Material, type the desired name into the box labelled "New blank material", and hit Create. Then, select your new Material from the "Loaded Materials" list.

Uh oh! Looks like the Material Editor has assigned an invalid default texture. Instead of textures/materials/plastic.jpg, it has assigned textures/materials/plastic.png. To fix this, scroll down to the "Color Map" input box, and change the value to the correct version. Then, scroll to the bottom, and Save changes:

---

---

Now it looks like the default plastic material, but we want to apply a custom shader to it.

Scroll back up to the Shader input box, and enter in the file name of your shader, without the extension:

Then, hit Save changes again.

Now, if you scroll back up to the preview, you will see a colored cube:

At this point, we have a valid Material, but hold on, what if we want to actually display it in the world? To do this, expand the Explorer window:

Then, click on the + next to the Workspace item:

From the new menu, select Mesh at the very top:

Then, in the Properties section, scroll down to Material and use the ... dropdown to select your material from the list:

That concludes this tutorial.

---

Troubleshooting

• Cube is purple-and-black: You have likely entered the wrong value into it's Material field
• Purple square in main viewport/Cube not visible: There is likely an error with the Shader Pipeline. Make sure you have:
  1. Saved your code in the Text Editor
  2. Clicked the Save & Reload button in the Pipelines window
  3. Copied the shader code correctly

If you see an error such as:

[ERRR]: Error while linking shader program 'awesome':
Link info
---------
error: "Frag_CameraPosition" not declared as an output from the previous stage

, try Save & Reload in the Pipelines window a second time.