Custom Shader FX Nodes - No Boilerplate

[00:00:00]Today, we're going to take a look at a new feature in Unity 6.5. [music] And if you take a look at this molten material we've got on the middle sphere, this is being created entirely by a shader graph node that I wrote, except I never touched the custom function node and I never wrote a single line [music] of C#. This is just an HLSL file. In Unity 6.5, there's a new shader function reflection API. You write a normal [music] HLSL function, you add two lines, and Unity turns it into a real shader graph node, [music] ports and all. Double-click the node and it opens the exact file. Let me show you how it works from an empty file to this.

[00:00:38]So, Unity 6.5 shipped with a whole bunch of shader graph upgrades. There's the expression node, a switch node, and there's subgraph improvements, but the reflection API is the big one for programmers. Now, Unity says it's meant to eventually replace both the custom function node and the old internal custom node API. It's actually really simple to use. It's just pure HLSL, there's no boilerplate. So, let's build a really simple one just so we can cover the syntax. So, you really only need three things to turn any HLSL function into a shader graph node. So, let's have a simple function that takes in a float2 UV, a float2 for speed along the X and Y, and a single float for time. So, inside the function, we can take the UV coordinate and we can scroll it smoothly over time by adding speed multiplied by time, and then we'll use the frac method to wrap the result between 0 and 1 so that the texture will loop endlessly without any visible jump. The frac method just throws away the whole number and keeps only the part after the decimal point. Now, here's what's different. We're going to start by including the shader API reflection support HLSL file. Including this gives us the Unity export reflection macro.

[00:01:47]This macro is telling Unity, "Reflect this function." Meaning, Unity will automatically read the function's inputs and outputs and create a real node with proper ports for you. Then finally, the third and the only mandatory ingredient is the provider key. This is a unique ID that Unity uses to identify and register your function as a node. Without it, the node simply won't appear in the create node menu. So here we're going to add it using special XML style comments right above the function. Every line starts with a triple slash, so we're going to embed this inside of a funk hints tag.

[00:02:20]Then we have our SG colon provider key.

[00:02:23]Here you can give it a unique name. And I'm also going to add a search category so that the node can appear neatly organized under a section Maleficent/UV in the create node menu instead of just getting lost in the list. Now make sure your file's saved and we're going to jump into Unity.

[00:02:38]So here in Unity I've created a basic unlit shader graph. If you need to do this, you just go up to assets, come under create shader graph under URP, select lit or unlit. We'll look at lit in a minute. So that'll give you this basic canvas here. Now right-click anywhere on the canvas and create a node. You'll see now I've got a section here where I've got all the shaders we're going to demo today. Here's the one we just made right in the UV category. Let's drop it onto the canvas here and have a look. Let's adjust this over just a little bit. Now take a look at the ports. Unity reflected them straight off the function signature. The three parameters became three input ports and the float two return became the output. So let's wire this thing up and do something with it. First of all, I'm just going to add some basic nodes to our graph here. Let's move the vertex and fragment over and then drop in a sample texture 2D. We can wire the output of our custom function into the UV input port and then we'll wire the output of our sample texture 2D right into the fragment's base color. Now let's also wire up some inputs. We could have a time node. We'll just wire that right into time.

[00:03:43]Let's also create a vector two node so we can wire that into speed.

[00:03:48]And then let's create a basic UV node and we'll pipe that right into UV. Now, of course, you can expose all these things to the Unity inspector, but let's just keep it simple. One more thing that we should add is some kind of texture into our sample texture.

[00:04:02]I'll just grab one here from my project.

[00:04:04]So, that's it, really. Of course, it's not doing anything because we haven't pumped anything into the speed values yet. Let's just set some values there, one and one. Then it should start moving in the preview there. Looks good so far.

[00:04:14]I'm going to click the save icon up in the top left. I've already added a material that uses the shader on to the quad in the back there. Let's jump into play mode and just see how it looks. So, there we go. Not too bad. We made a custom function in HLSL and with almost no effort at all, we were able to turn it into a shader graph node and hook it up to some basic elements in no time.

[00:04:35]So, that's really just the basics of this functionality. Let's see how we can take it further.

[00:04:41]So, we just saw how ports inherit the names and types from our code, which is great, but we can do better with hints.

[00:04:47]Let's make a function that takes a color and desaturates it to grayscale using luminance and then tints it with a color based on a strength value. So, it's a very simple function. It's just creating a nice duotone or a colored look from any input color. Just like before, we're going to include the shader API reflection support HLSL file. We're going to use the Unity export reflection macro. I'm going to add a provider key and a search category. Notice this time I've also added a tag for display name.

[00:05:16]This is what shows up as the title of the node in shader graph. And now we're going to add parameter hints. One block per input matched exactly to the parameter name in the function. Let's start with tint. First of all, notice the SG colon color. This turns the tint parameter into a nice color picker instead of three number fields. And Unity type checks it, so it only works on float three or float four. Let's also make a hint for the strength field.

[00:05:42]Here, I'm going to use SG colon range and this turns strength into a clean zero to one slider. And you can see also that I've used the SG:Default tag to give both of these ports some reasonable starting values. Now, let's save this file and get back to Unity.

[00:05:57]So, I've already created a lit URP Shader Graph. Let's open it up. Just like before, let's right-click on the canvas, select create node. This time I expect to find it under the color section, and there it is, colorize. Now, let's have a close look at these ports that were created. First of all, I'll connect the out into the base color of the fragment shader, and then let's zoom in a little bit here. If we take a look at what's going on with tint now, because we made that parameter hint, we now get a nice color picker here right on the port. Of course, we could do the same for the color parameter if we wanted to, but because we didn't, it's just taking in a basic float 3. Let's set some kind of value in there, maybe 25. Now that we have a real color and not pure black, we can use the tint to actually change the color. Below that, we've got strength as a slider, so we can just slide it up and down to change the strength of that tint being applied to the base color. So, anyway, let's just pick a color here, maybe something in the green, then maybe we can slide the strength all the way up to 1. So, with a color picker on tint and a slider on strength and some clean display names, we've got a node that looks like it actually shipped with Unity, but all we've really done is define that in a comment block.

[00:07:09]So, let's go over one more. We're not going to do this one line by line because it has a lot of helper functions and whatnot. Let's just run through it quickly together. You can see at the top I've got the same include statement, then I've defined three helper methods that I'm going to use in this procedural shader. The thing I really want to point out here is that these are just helper methods. Only the function with the export macro will actually become a node. So, your exported node can actually contain quite a lot of extra functionality. This one's using helper methods, but you can include noise, SDFs, even SRP shader library functions, and hide them all behind this one node.

[00:07:43]And let's take a look at one other new trick which has to do with outputs. This API supports in, out, and in out parameters plus a void return. So, one node can drive two things at once as you can see here. We're going to output albedo and emission from this node. I've already saved it. Let's go add this to a lit shader graph.

[00:08:04]I'll leave all the code samples for this in a repository somewhere. Link will be in the description. Let's drop this node onto the canvas. You can see it's quite a bit more complex than the previous ones. There's a lot more input. You can also see that we now have two output ports. Let's connect those up first.

[00:08:18]I'll just drag the albedo port out into the base color and we'll drag emission into emission of the fragment shader.

[00:08:26]Now, you can see we've got our color pickers and our sliders for various things because they were defined in comments. But, let's drop a UV node in here so we can drag it right into the UV input. Then, we also need a time node just like we made before. Let's hook that up to the time port. So, what did we just build? Well, I named it energy field. Of course, if we change the colors, it would probably look that way.

[00:08:48]But, really right now it's making a procedural molten lava effect just using a bit of noise. The inputs are all simple. The outputs are simple. Before Unity 6.5's shader function reflection API, creating an effect like this would have required either a huge messy chain of basic nodes or much more cumbersome custom function node with a lot of manual setup. So, let's jump into play mode and have a look. Not too bad, right? So, that's it. That's the shader function reflection API. You write normal HLSL. You just add a couple lines plus [music] some optional hints and Unity automatically turns your function into a real professional-looking [music] shader graph node. No more messing around with the custom function node and no C# required. I also heard, though I haven't looked at it yet, but there should be some new [music] samples with the shader graph package. One of of has some use cases for this reflection API as well. Just remember, this is [music] only for Unity 6.5 and of course the new version of Shader Graph, which is 17.5.

[00:09:44][music] So, with that I'm going to wrap it up.

[00:09:47]I'll leave some links in the description. Of course, join us on Discord if you're so inclined and subscribe to the channel. We've got a new video every Sunday. I'll throw another video up on the screen. Maybe I'll see you there.