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.

Setup

Firstly, you need to prepare your Development Environment, assuming it isn't already set-up.

• Open your phoenix.conf in the root directory (i.e., the directory that contains the resources subdirectory)
• It should look something like this:

{
  "DefaultWindowSize": [
    1280,
    720
  ],
  "Developer": true, // The important part
  "GameTitle": "PhoenixEngine",
  "ResourcesDirectory": "resources/",
  "RootScene": "scenes/root.world",
}

• Ensure that Developer is set to true, as this will enable all the necessary UIs

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. Click on the hyperlink labelled "Vertex Shader" to open it in the built-in Text Editor:

For demonstration purposes, let's use a custom vertex shader. From the File menu of the Text Editor, hit the New button:

Note that this is not supposed to be a GLSL or graphics programming tutorial. 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;
}

Go back to the File menu, and hit Save as.

In the opened File Dialog, save your shader file somewhere inside your resources/shaders directory.

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.

Next, the Fragment shader. Click the File > New button from the Text Editor again, and copy in the following code:

#version 460 core

in vec3 Frag_VertexNormal;

out vec4 FragColor;

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

Then, hit Save as again, saving it with .frag as the extension instead within the resources/shaders folder.

Now, hit Close in the File menu to close the Text Editor. Go back to the Shader Pipelines window, hit the ... next to the Fragment Shader hyperlink, and choose the Fragment Shader file you created.

Then, scroll to the bottom of the Shader Pipelines widget, and hit 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:

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 hit 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 Editor 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 enter the name of our Material:

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.