Shader Tool
Shaders are powerful tools for creating impressive visual effects. This page will go over how to use the Shader Tool to quickly experiment with shaders while making tModLoader mods. This is not a guide on how to program shaders, or how to use them within your mod's code, those are both explained in the Expert Shader Guide on the tModLoader wiki. Once you are familiar with shaders, you can use the Shader Tool to quickly test shaders.
Here are some short videos showing the capabilities of the tool. Read below to find out more.
Quickly iterating on shader code. Live building of edits:
Testing shader parameters.
Depending on what you are attempting to do with shaders, you'll want to follow one of the following workflows. The Shader Tool allows testing new shaders, as well as re-building existing shaders.
If you are working on a mod, you can recompile existing shaders or compile a new shader. Recompiling existing shaders allows you to quickly experiment with your shader code to find the desired effect. Compiling a new shader might be more convenient than downloading the fxcompiler program mentioned in the Expert Shader Guide
First, open up the Shader Tool by clicking the small button to open the toolbar and then click the "Click to toggle Shader Tool" button:
Next, you should see the Shader Tool:
On the top, you'll see the Mod Sources panel, here you should see a list of all currently enabled mods. Find your mod and click it. Once you have done that, the panel below that will populate with existing shaders.
If the shader only exists as a .fx file and has yet to be compiled and loaded into the mod, the entry will mention (unloaded). All other shaders already loaded will not show (unloaded). Clicking on the entry should open the .fx file in your selected text editor. You may get a message telling you that you need to associate a text editor with .fx files. Clicking on the Compile button will attempt to compile the specified shader. The Watch Mod Sources checkbox will automatically check itself, this feature will track the .fx files for changes and automatically recompile the shader every time you save the file. Leaving this feature on will allow you to test your shader in real time as you save your changes. The chat messages will indicate success or failure.
At this point, you can leave tModLoader on one side of the screen and your text editor on the other side. Each time you change the .fx file, the shader will update in-game. You'll have enable the shader yourself as you would normally to see the shader in effect.
Note that currently the Shader Tool will automatically replace shaders populated into GameShaders.Hair/Armor/Misc, shaders assigned to Filters, and shader entries retrieved from mod.GetEffect("shadername"). If your shader is bound elsewhere, you might not see your shader update in-game. If you cache the result of mod.GetEffect("shadername") somewhere, you will also not see the shader update and should avoid caching while testing. The chat messages will let you know how many entries have been automatically updated:
If you want to experiment with shader code, the Shader Tool can generate Armor or Screen shader templates. First, select which template you want to generate by clicking the radio button, then, click Create/Recreate Test Shader. Once you do this, the special test shader file will be created in "\Terraria\ModLoader\Mods\Cache\ModdersToolkit_Shader.fx". Clicking Edit Test Shader will open the file for you in your text editor. The test shader has no effect right now. As a test, simply insert color.g *= 2.0; into the shader code:
float4 color = tex2D(uImage0, coords);
color.g *= 2.0; // <- Add this line
return color;
Now, save the file. You'll have to now click the Compile Test Shader button. If you were testing an armor shader, you should see a message informing you to wear Acid Dye (cheat it in if you don't have it, you can run Main.LocalPlayer.QuickSpawnItem(3040, 99) in the REPL to get the dye). Wearing the dye, the effect of doubling the green values in our shader should be noticeable (it is very noticeable when wearing Rain Coat and Rain Hat).
If you were testing a screen shader, click Force Shader Active and the screen should become tinted green.
Clicking the Compile Test Shader button all the time will get old, so lets check Watch Test Shader File and then edit color.g *= 2.0; to become color.r *= 2.0;. Now, save the file. You should see the shader update within a second or 2, showing a red tint now:
Now you can easily test the various examples in the Expert Shader Guide. If you are happy with a shader, you can copy the .fx file to your mod's source folder, just make sure to rename the pass to something more appropriate. After that, make sure to compile the shader once more from the Mod Source panel so the .xnb file is generated, then rebuild your mod to package the built shader within it.
The parameters uColor and uIntensity are exposed on the Shader Tool, but only for testing screen shaders in the current version. To test this, once again replace our simple effect, color.r *= 2.0;, with color.r += uIntensity;. Once the shader is compiled and enabled, drag the slider. The tint on the screen should update accordingly. As a test for tweaking uColor, replace the code once again with color += float4(uIntensity * uColor, 0);. Now you should be able to tweak the color and the intensity of that color that is added to this screen shader. These 2 parameters correspond to the UseColor and UseIntensity methods of ScreenShaderData that you assign when creating a Filter or when tweaking the Filter in ModPlayer.UpdateBiomes
While testing screen shaders, "Images/Misc/Perlin" and "Images/Misc/noise" are bound to uImage1 and uImage2, respectively. You can use these 2 textures to quickly test using additional textures in screen shaders. To test this, copy the shader code (just the code in PixelShaderFunction, nothing else) from ExampleEffectDeath.fx and paste it in the test screen shader, replacing all the code within PixelShaderFunction. Replace uOpacity within this code with uIntensity, then save. The actual logic in this shader are beyond the scope of this guide, but if you did it right, you should be able to see the effects of the Perlin texture used in the code. You can replace uImage1 with uImage2 to test the noise texture:
