S&box Wiki
Home
/
Edit Anatomy of Shader Files
View
Edit
History
No Category
Developer Overview
The Project System
Publishing To Asset Party
Getting Started With Hammer
Mapping Basics
Mapping Entities
Advanced Mapping Techniques
Getting Started with Modeldoc
Animgraph & Animation
Physics
Modeldoc Nodes
Advanced Modelling
UI Basics
Styles & Stylesheets
Razor Templates
Game Menus
Materials
Built In Shaders
Shaders
Shader Reference
Sounds & Audio
Particles
Getting Started
Making Games
Input
Networking
Physics
Rendering
Editor & Tools
VR
Misc
Playing Guides
Console Commands & Variables
Dedicated Server
Log in to edit
Anatomy of Shader Files
<cat>Material.ShaderReference</cat> <title>Anatomy of Shader Files</title> # What is a shader File? The `.shader` file is a container for your shader program. Its main purpose is to eliminate the need for multiple shader files for each shader stage. The `.shader` file is a plain text file and it can be opened in any code/text editor and the underlying shader format is HLSL. The `.shader` is split into multiple different sections separated by a header and curly brackets. An example of the SHADER format can be seen below: ``` //========================================================================================================================= // Optional //========================================================================================================================= HEADER { Description = "Template Shader for S&box"; } //========================================================================================================================= // Optional //========================================================================================================================= FEATURES { #include "common/features.hlsl" } //========================================================================================================================= COMMON { #include "common/shared.hlsl" } //========================================================================================================================= struct VertexInput { #include "common/vertexinput.hlsl" }; //========================================================================================================================= struct PixelInput { #include "common/pixelinput.hlsl" }; //========================================================================================================================= VS { #include "common/vertex.hlsl" // // Main // PixelInput MainVs( VertexInput i ) { PixelInput o = ProcessVertex( i ); // Add your vertex manipulation functions here return FinalizeVertex( o ); } } //========================================================================================================================= PS { #include "common/pixel.hlsl" // // Main // float4 MainPs( PixelInput i ) : SV_Target0 { Material m = Material::From( i ); /* m.Metalness = 1.0f; // Forces the object to be metalic */ return ShadingModelStandard::Shade( i, m ); } } ``` # HEADER The shader `HEADER` section gives information about the header and sets the compile targets. The following options can be set: | Key | Value Type | Example | Explanation | |-----|------------|---------|-------------| | Version | Number | `Version = 1;` | Sets a version number for your shader, this is shown in the Material Editor | | DevShader | Boolean | `DevShader = true;` | If your shader is marked as a dev shader, you can reload your shader in the Material Editor | | Description | String | `Description = "My shaders description";` | A description of your shader which is shown to the user in the material editor | | DebugInfo | Boolean | `DebugInfo = true;` | Ships debug information with your shader, this is only useful for developing shaders. Shipping shaders with this will drastically increase the file size | ``` HEADER { Description = "My shaders description!"; } ``` # FEATURES Features allow you to add customization to your shaders in the form of using the shader preprocessor(note that this is different from the HLSL preprocessor). Features allow you to specify conditions on attributes, sampler settings, or render states. Features MUST be defined within the `FEATURES` section and feature names MUST start with `F_`! Features have multiple different configurations and settings, you have regular checkboxes, radio buttons and rulesets to only allow one feature or the other. Features are defined as follows: `Feature(F_FEATURE_NAME, RANGE_MIN..RANGE_MAX, "Feature Category");` ## Checkbox ``` Feature(F_MY_FEATURE_NAME, 0..1, "This is a category"); Feature(F_MY_FEATURE_NAME2, 0..1, "This is a category"); Feature(F_MY_FEATURE_NAME_3, 0..1, "This is a category"); ``` `MY_FEATURE_NAME` is transformed into `My Feature Name`. All underscores are converted into spaces within the material editor. The range `0..1` indicates that this is a checkbox. These checkboxes will also share the same category. <upload src="653cb/8d9850202fbd29f.png" size="23270" name="2021-10-03_36-02-06f903ab-202e-4441-b29d-934b69d84180-v9q57xG2.png" /> ## Categories You can create another category by providing a different category name. ``` Feature(F_DO_SOMETHING, 0..1, "This is another category"); ``` <upload src="653cb/8d98502490cf769.png" size="12134" name="2021-10-03_36-59-f61684e9-5754-437b-a0e9-28aa881a5ec0-KDNvT2rL.png" /> ## Radio buttons Features also allow you to have radio buttons. A group of buttons that only allow one choice. This is done by specifying a range that is greater than `0..1` within the feature and providing the names of each radio button. It can be done as so: ``` Feature(F_RADIO_FEATURES, 0..3(0="Checkbox 1", 1="Checkbox 2", 2="Checkbox 3", 3="Checkbox 4"), "This is another category"); ``` ## Feature rules Feature rules allow you to limit the section of options. It works similarly to radio buttons however it's a bit more fine control. Feature rules are defined as follows: `FeatureRule(RULE(F_FEATURE1, F_FEATURE2, ...), "A useful tooltip");` Below is a list of feature rules: | Rule | Arguments | Example | Info | |------|-----------|---------|------| | AllowN | F_FEATURE_0, F_FEATURE_N | `FeatureRule(Allow1(F_FEATURE1, F_FEATURE2, F_FEATURE3), "You can only pick one!");` | N is any number | ## Using features As features are only run through the shader preprocessor, you can only use them in such things as within render states. An example of their usage can be used as below: ``` FEATURES { Feature(F_ENABLE_DEPTH, 0..1, "Settings!"); } PS { RenderState( DepthEnable, F_ENABLE_DEPTH ? true : false ); } ``` ## Example ``` FEATURES { Feature(F_MY_FEATURE_NAME, 0..1, "This is a category"); Feature(F_MY_FEATURE_NAME2, 0..1, "This is a category"); Feature(F_MY_FEATURE_NAME_3, 0..1, "This is a category"); Feature(F_DO_SOMETHING, 0..1, "This is another category"); Feature(F_RADIO_FEATURES, 0..3(0="Checkbox 1", 1="Checkbox 2", 2="Checkbox 3", 3="Checkbox 4"), "This is another category"); // Features MUST begin with F_ Feature(F_ENABLE_DEPTH, 0..1, "Settings!"); Feature(F_A_CHECKBOX_FEATURE, 0..3(0="Radio 1", 1="Radio 2", 2="Radio 3", 3="Radio 4"), "Category name"); Feature(F_ONLY_ALLOW_ONE_1, 0..1, "Feature rules"); Feature(F_ONLY_ALLOW_ONE_2, 0..1, "Feature rules"); Feature(F_ONLY_ALLOW_ONE_3, 0..1, "Feature rules"); FeatureRule(Allow1(F_ONLY_ALLOW_ONE_1, F_ONLY_ALLOW_ONE_2, F_ONLY_ALLOW_ONE_3), "Hover over hint"); } ``` <upload src="653cb/8d98500c7a33e2e.png" size="29587" name="2021-10-03_27-08-b859b709-0c90-48ed-9a8e-a8b30188ae55-D5UkXcfi.png" /> # Common The common section is any information that is shared between all shader stages. This can include anything from defines, includes functions, etc. An example can be seen below: ``` COMMON { #define SOME_GLOBAL_DEF } PS { #define LOCAL_DEF #ifdef SOME_GLOBAL_DEF // This is seen #endif #ifdef LOCAL_DEF // This is seen #endif } VS { #ifdef SOME_GLOBAL_DEF // This is seen #endif #ifdef LOCAL_DEF // This is not seen! #endif } ``` # Shader Inputs/Outputs <warning>As of March 2024, Hull and Domain stages have been removed and won't work. If your shader uses HS/DS programs, it's recommended to remove them from your code. HS/DS stages are still referenced on this page for archival purposes. </warning> The shader inputs and outputs are structs that act like sections. If you noticed in the sample file, they are defined in the same area as headers are. There are multiple different inputs and outputs which you can use: | Input/Output | Stage | Name | Alternate Name | Note | |--------------|-------|------|----------------|:-----| | Input | Vertex | VertexInput | VS_INPUT | | | Input | Pixel/Fragment | PixelInput | PS_INPUT | | | Input | Geometry | GeometryInput | GS_INPUT | | | Input | Geometry | HullInput | HS_INPUT | **Deprecated** | | Input | Domain | DomainInput | DS_INPUT | **Deprecated** | | Output | Vertex | VertexOutput | VS_OUTPUT | | | Output | Pixel/Fragment | PixelOutput | PS_OUTPUT | | | Output | Geometry | GeometryOutput | GS_OUTPUT | | | Output | Geometry | HullOutput | HS_OUTPUT | **Deprecated** | | Output | Domain | DomainOutput | DS_OUTPUT | **Deprecated** | ## Example ``` struct VertexInput { float3 vPositionOs : POSITION < Semantic( PosXyz ); >; float4 vNormalOs : NORMAL < Semantic( OptionallyCompressedTangentFrame ); >; float2 vTexCoord : TEXCOORD0 < Semantic( LowPrecisionUv ); >; } // OR struct VS_INPUT { float3 vPositionOs : POSITION < Semantic( PosXyz ); >; float4 vNormalOs : NORMAL < Semantic( OptionallyCompressedTangentFrame ); >; float2 vTexCoord : TEXCOORD0 < Semantic( LowPrecisionUv ); >; } ``` # Shader Stages <warning>As of March 2024, Hull and Domain stages have been removed and won't work. If your shader uses HS/DS programs, it's recommended to remove them from your code. HS/DS stages are still referenced on this page for archival purposes. </warning> There is a section for each dedicated shader stage, the valid shader stages are as follows: | Stage | Name | Entry Point | Notes | |-------|------|-------------|:------| | VS | Vertex Shader | MainVs | | | PS | Pixel/Fragment Shader | MainPs | | | GS | Geometry Shader | MainGs | | | HS | Hull Shader | MainHs | **Deprecated** | | DS | Domain Shader | MainDs | **Deprecated** | | CS | Compute Shader | MainCs | | A shader can have as many unique stages as you like. Typically you'll be using `PS` and `VS` in most shaders. ## Example ``` VS { #include "common/vertex.hlsl" // // Main // PixelInput MainVs( VertexInput i ) { PixelInput o = ProcessVertex( i ); // Add your vertex manipulation functions here return FinalizeVertex( o ); } } ```
S&box Wiki
Development
Developer Overview
6
Editor Overview
General FAQ
System Requirements
The s&box wiki
Troubleshooting
Useful Links
The Project System
4
Adding Assets
Creating a Game Project
Project Settings Window - Games
Project Types
Publishing To Asset Party
2
Uploading assets
Uploading projects
Hammer
Getting Started With Hammer
3
Getting Started With Hammer
Making Your First Map
Mapping Resources
Mapping Basics
7
Cordons
Hotspot Materials
Selection Sets
Standard Mapping Dimensions
Tool Materials
Tools Visualisation Modes
Using Entities That Require a Mesh
Mapping Entities
2
Creating a Door
Light Entities
Advanced Mapping Techniques
8
Collaborating With Prefabs and Git
Instances
Prefabs
Quixel Bridge Plugin
Tilesets
Tilesets-Advanced
Tilesets-Proxies
VIS Optimizations
Models & Animation
Getting Started with Modeldoc
7
Automatic Model Setup
Breakpieces
Creating a Model
Guide to Models
Importing Rust Weapons
LODs
ModelDoc FAQ & best practices
Animgraph & Animation
4
Animations without Animgraph
AnimEvents, AnimGraph Tags, Attachments
Animgraph
Delta Animations
Physics
3
Cloth Physics
Collisions, Physics & Surface Types
Jiggle Bones
Modeldoc Nodes
1
Custom ModelDoc nodes
Advanced Modelling
6
Bodygroups
Citizen
First Person
IKChains and Stride Retargeting
Morphs
Vertex Normals
User Interface
UI Basics
7
Custom Fonts
Embedding Websites
Enabling Pointer Events
Events and Input
Localization
UI Basics
UI with Components
Styles & Stylesheets
1
Video Backgrounds
Razor Templates
4
A Razor Overview
Aliases and SetProperty Attributes
Generic Components
Templates
Game Menus
1
Making a Custom Pause Screen
Materials & Shaders
Materials
5
Guide to Materials
Material Attributes
Material Resources
Texture Settings
Using Dynamic Expressions
Built In Shaders
2
Foliage Shader
Glass Shader
Shaders
4
Compute Shaders
Constant Buffers
Material API
Shading Model
Shader Reference
5
Anatomy of Shader Files
Getting rid of Tex2D macros
Shader Reference
Shader States
Texture Format Cheat-Sheet
Other Assets
Sounds & Audio
3
Guide to Sounds
Sound Events
Soundscapes
Particles
5
Creating animated sprites
Creating your first particle effect
Understanding Particle Editor
Using custom sprites
Using particle systems from C#
Coding
Getting Started
5
Cheat Sheet
Learning Resources
Setting up Rider
Setting up Visual Studio
Setting up Visual Studio Code
Making Games
2
Components
GameObjects
Input
4
Commands
ConVars
Input System
Speech Recognition
Networking
7
Auth Tokens
Http Requests
Lobby System
Networked Types
Networking Basics
RPCs
WebSockets
Physics
4
Collisions
Hitboxes
Traces
Triggers
Rendering
3
Render Tags
RenderHooks
Scenes
Editor & Tools
7
Creating a Tool
Custom Asset Types
Guide to Widgets
Hammer API
Hammer Gizmos
Hotload Performance
Widget Docking
VR
3
Getting Started
VR Input
VR Overlays
Misc
13
Asset Types
Attributes and Component Properties
Backend API
Cloud Assets in code
Code Accesslist
CPU Performance Profiling
DisplayInfo
FileSystem
Mounting assets at runtime
package/find
Setting Up A Navigation Mesh
Threaded Tasks
TypeLibrary
Playing
Playing Guides
3
Default Keybinds
Proton
s&box on macOS (Experimental)
Console Commands & Variables
1
Launch Arguments
Dedicated Server
1
Dedicated Servers