Markdown-like syntax for shaders, to make better material inspectors. Works with ShaderGraph, Amplify, BetterShaders, custom shaders, ...
npm install com.needle.shadergraph-markdownToggle ShaderGraph Markdown.
Needle.MarkdownShaderGUI.
# Hello Foldout. You don't need to change the reference name.
Package Manager > Shader Graph Markdown > Samples.
# My Foldout) and they'll display beatifully in your Shader Graph blackboard.
& appended to render them as smaller inline textures. If you use &&, the next property will be rendered right next to it, a common pattern throughout URP and HDRP for drawing sliders, colors etc. right next to a texture property. They'll be auto-indented in the Blackboard.
!REF property draws an enum or boolean keyword.
KEYWORD_OPTION.
and, &&, or, ||, !, >, <= ... and other operators - please let us know if something doesn't work as expected!
Refactor Shader Properties
Window > Needle > Refactor Shader Properties
Markdown Tools section of the material inspector.
Markdown Tools section (formerly: Debug) that contains info and helpers to configure your custom UI, and to work with properties and keywords.
Debug Conditional Properties is helpful when you're setting those up, as it will show all properties and allow you to quickly check for wrongly set up conditions.
MinMaxDrawer, VectorSliderDrawer, GradientDrawer etc.) should be a pretty good starting point.
!DRAWER DoSomethingDrawer and !DRAWER DoSomething.
!DRAWER MinMax _MyVector
_MyVector.z to _MyVector.w with min = _MyVector.x and max = _MyVector.y.
!DRAWER MinMax _MyVector DisplayName
!DRAWER MinMax _MyVector.x _MyVector.y
min = _MyVector.x and max = _MyVector.y.
!DRAWER MinMax _MyVector.x _MyVector.y DisplayName
!DRAWER MinMax _MyVector.x _MyVector.y MetallicRemap
!DRAWER MinMax _MyVector.z _MyVector.w SmoothnessRemap
`
#### VectorSlider
!DRAWER VectorSlider _MyVector (First Slider, Second Slider, Third Slider)
Draws separate 0..1 sliders for the invidiual vector properties.
The display name will come from _MyVector.
VectorSlider drawers can be used with a shorthand (&):
My Vector (First Slider, Second Slider, Third Slider) &
You can also use this to hide parts of a vector:
My Vector (R, G) will only draw R and G sliders and ignore the remaining ZW values.
#### Gradient
!DRAWER Gradient _MyRampTextureSlot
Draws a gradient field that automatically generates a gradient lookup texture whenever the value is changed.
#### MultiProperty (experimental)
!DRAWER MultiProperty _Color1 _Color2 _Color3
Draws all properties in the same line.
This works pretty well for combining a couple of colors or numbers into inline drawers β please note that there's a good amount of combinations where this will fail, simply because there's not enough space on one line to hold the data you might want to show.
Attribute Reference
1. # Foldout
A foldout header
6. ## Header
A header, similar to the [Header] attribute in scripts
4. ### Label
A regular label, not bold and with no extra space.
Useful before indented properties.
1. Append && to Texture properties
- this will render the _next_ property inline (most useful for Color or Float properties)2
- if the next property is named _MyTex_ST (with _MyTex matching the texture property name), a tiling/offset field will be drawn
3. Append & to Vector properties to have them display as 0..1 sliders
- You can optionally specify the slider names: Vector with Sliders (Amplitude, Frequency, Pattern) &
- If you leave them out you'll simply get a bunch of X,Y,Z,W sliders
- If the vector property starts with _Tiling or _Tile or ends with _ST, it will be drawn as Tiling/Offset property field
3. Append & to Texture properties to render them as small texture slot
(not the monstrous default Shader Graph one, the nice one that URP/HDRP use for everything)
8. Prepend a number of dashes (e.g. - or ---) to indent properties.
Nice for organization and showing where conditionals belong.
9. !NOTE Any note text1
8. Link Text1
A web link.
9. !TOOLTIP Any text
Tooltip for the following property. !TIP has the same effect.
10. !REF KEYWORD_NAME
A reference to a bool/enum keyword to be drawn here - by default they end up at the end of your shader, with this you can control exactly where they go.
You can also reference and thus edit a global keyword, but be aware that changing that value will change it, well, globally!
4. Conditional properties: Append [SOME_KEYWORD] to your foldouts, drawers or properties to only make them show up when the condition is met. Conditions can be
- boolean keywords (make sure to include the _ON part)
- global keywords
- enum keywords
- texture properties (when the texture is not null)
- boolean properties (when the bool is true)
- float properties (compare using <, >, == etc.)
- color properties (max(r,g,b) is used as comparison value)
- vector properties (vector length is used as comparison value)
Conditions always come _last_, even for inline properties.2
7. !DRAWER MyDrawer
This will draw custom code, similar to a PropertyDrawer for the Inspector. Drawers are specified as subclasses of MarkdownMaterialPropertyDrawer.
Examples:
- Define !DRAWER Gradient _MyTextureProperty to render a nice gradient drawer that will generate gradient textures in the background for you.
- Define some colors, and _before_ them add !DRAWER MultiProperty _Col1 _Col2 _Col3. This will render three colors all in one line.
8. # (hash with nothing else)
End the current foldout. This is useful if you want to show properties outside a foldout, in the main area, again.
1: Will not be shown if the previous property was conditionally excluded.
2: When you're using conditional properties as well, conditions come after inlining, and the next property needs to have the same condition. _MyTex && [_SOME_CONDITION] and on the next line _MyColor [_SOME_CONDITION].
A lot of the above can be combined - so you can totally do --!DRAWER MinMax _MinMaxVector.x _MinMaxVector.y [_OPTIONAL_KEYWORD && _Value > 0.5] and that will give you a double-indented minmax slider that only shows up when _OPTIONAL_KEYWORD is set and _Value has a value of greater than 0.5.
Notes
$3
HDRP Shader Graphs are supported. A speciality there is that these already have custom shader inspectors. Shader Graph Markdown finds and displays the "original" inspector in addition to your own properties.
!HDRP Support
That being said, HDRP does some keyword magic (resetting material keywords at times); if you find something doesn't work as expected, you can use the "Debug" section to reset keywords and/or show the original property list.
$3
Amplify works as-is, you can specify Needle.MarkdownShaderGUI as custom shader inspector and then create properties as usual. You'll have to arrange them somewhere on the board though (they need to be somewhere). Also, turn on "Auto-Register" on the markdown properties, otherwise they'll be stripped away since they are not actually "used" in the shader.
!Amplify Properties
!Amplify Auto-Register
$3
Nothing about the custom shader inspector in Shader Graph Markdown is actually Shader Graph-specific! You can use the same properties and drawers for all shaders, be it built-in, surface shaders, BetterShaders, other editors... In many cases, you could also use custom attributes, but especially for foldouts and drawers, Shader Graph Markdown gives a lot of flexibility.
$3
Unity's GI systems rely on "magic property names" to work. Namely, _EmissionColor (Color) and _EmissionMap (Texture) have to be present; if either is missing, the resulting emission will be black (no emission). If both are present, SG Markdown will render the lightmap dropdown to choose "Baked", "Realtime" or "None" for Global Illumination.
If the _Emission (or _EMISSION) property toggle is present, you can override this, and e.g. make materials that are emissive (they are bright) but don't contribute to GI.
This is a typical setup that will hide the EmissionColor and EmissionMap properties if emission is turned off:
`
[Toggle(_EMISSION)]_Emission("Emission", Int) = 0
[HDR]_EmissionColor("EmissionColor [_EMISSION]", Color) = (0,0,0,1)
_EmissionMap("EmissionMap [_EMISSION]", 2D) = "white" {}
``