Skip to content

Commit 142c72a

Browse files
tebjantebjan
committed
Add VS Code shader development documentation
- New page: shader-development-vscode.md with full development guide - Update custom-shaders.md with VS Code as Option 2 - Add VSCodium and OpenVSX alternatives - Document IntelliSense, inheritance features, and Assets folder requirements - Add link in effects-and-shaders index
1 parent 51d4896 commit 142c72a

File tree

3 files changed

+355
-2
lines changed

3 files changed

+355
-2
lines changed

‎en/manual/graphics/effects-and-shaders/custom-shaders.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ You can also use custom shaders to create custom post effects. For more informat
1111

1212
## Create a shader
1313

14+
### Option 1: Using Visual Studio (Recommended for Game Studio workflow)
15+
1416
1. Make sure you have the [Stride Visual Studio extension](../../get-started/visual-studio-extension.md) installed. This is necessary to convert the shader files from SDSL ([Stride shading language](index.md)) to `.cs` files.
1517

1618
2. In Game Studio, in the toolbar, click ![Open in IDE](../../get-started/media/launch-your-game-ide-icon.webp) (**Open in IDE**) to open your project in Visual Studio.
@@ -63,6 +65,29 @@ You can also use custom shaders to create custom post effects. For more informat
6365

6466
![Reload assemblies](../../particles/tutorials/media/reload-assemblies.png)
6567

68+
### Option 2: Using Visual Studio Code (Advanced shader development)
69+
70+
For shader-focused development with enhanced IntelliSense and inheritance visualization:
71+
72+
1. Install [Visual Studio Code](https://code.visualstudio.com/) or [VSCodium](https://vscodium.com/)
73+
2. Install the **Stride Shader Tools** extension:
74+
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=tebjan.sdsl)
75+
- [OpenVSX](https://open-vsx.org/extension/tebjan/sdsl) (for VSCodium and other alternatives)
76+
3. Create your `.sdsl` file in your project's **Assets** folder (or a subfolder within Assets)
77+
78+
>[!Note]
79+
>Shaders must be in the **Assets** folder of your package (the folder containing the `.sdpkg` file). This is part of Stride's [project structure](../../files-and-folders/project-structure.md).
80+
4. VS Code provides:
81+
* Context-aware completions for inherited members, streams, and semantics
82+
* Live inheritance tree visualization
83+
* Go-to-definition through the shader hierarchy
84+
* Real-time error reporting
85+
86+
For detailed information on shader development with VS Code, see [Shader development with Visual Studio Code](shader-development-vscode.md).
87+
88+
>[!Note]
89+
>When using VS Code for shader authoring, you still need Visual Studio with the Stride extension to generate the `.cs` files that Game Studio requires. The typical workflow is: develop and edit shaders in VS Code, then open the solution in Visual Studio to trigger the code generation, and finally reload assemblies in Game Studio.
90+
6691
The **Asset View** lists the shader in the same directory as your scripts (eg **MyGame.Game**).
6792

6893
![Shader in Asset View](media/shader-in-asset-view.png)
@@ -172,9 +197,9 @@ Then you can set the value in the material properties:
172197

173198
You can access the compilation logs of your shaders through the Game Studio's debug window's EffectCompilerCache tab (`Ctrl+Shift+D` or `Help`>`Show debug window`).
174199

175-
The launcher hosts a Visual Studio extension specifically for syntax highlighting and errors you may want to use.
200+
The launcher hosts a Visual Studio extension specifically for syntax highlighting and errors you may want to use. For advanced shader development with enhanced IntelliSense, see [Shader development with Visual Studio Code](shader-development-vscode.md).
176201

177-
The engine's source also provides a good reference point for how one would write shaders. To that end [Stride.ShaderExplorer](https://github.com/tebjan/Stride.ShaderExplorer) facilitates the act of finding and browsing through the different shaders the source contains.
202+
The engine's source also provides a good reference point for how one would write shaders. [Stride.ShaderExplorer](https://github.com/tebjan/Stride.ShaderExplorer) is an excellent standalone tool for browsing and exploring the complete shader library and their inheritance relationships.
178203

179204
A common issue you may stumble onto is the following:
180205
> E1202: The mixin X in Y dependency is not in the module

‎en/manual/graphics/effects-and-shaders/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,4 @@ For mobile platforms, shaders are optimized by a GLSL optimizer to improve perfo
4343
- [Templates](shading-language/templates.md)
4444
- [Shader stage input/output automatic management](shading-language/automatic-shader-stage-input-output.md)
4545
* [Custom shaders](custom-shaders.md)
46+
* [Shader development with Visual Studio Code](shader-development-vscode.md)

‎en/manual/graphics/effects-and-shaders/shader-development-vscode.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
# Shader development with Visual Studio Code
2+
3+
<span class="badge text-bg-primary">Intermediate</span>
4+
<span class="badge text-bg-success">Programmer</span>
5+
6+
The **Stride Shader Tools** extension for Visual Studio Code provides language server features for SDSL shader development with intelligent code completion and navigation.
7+
8+
For information on the SDSL language itself, see [Shading language](shading-language/index.md). For using shaders in materials, see [Custom shaders](custom-shaders.md).
9+
10+
## Features
11+
12+
The VS Code extension provides:
13+
14+
* **Syntax highlighting** for SDSL (`.sdsl` files)
15+
* **IntelliSense** with context-aware completions
16+
* **Inheritance tree visualization** in a dedicated sidebar panel
17+
* **Member explorer** showing all available methods and variables
18+
* **Go-to-definition** through the inheritance hierarchy
19+
* **Hover documentation** for types, methods, and semantics
20+
* **Real-time diagnostics** for parse errors and type issues
21+
* **Shader debugging** with RenderDoc integration *(in development)*
22+
23+
## Installation and setup
24+
25+
### Prerequisites
26+
27+
* [Visual Studio Code](https://code.visualstudio.com/) or [VSCodium](https://vscodium.com/)
28+
* .NET 8 SDK (the extension will prompt you to install if not present)
29+
30+
### Installation
31+
32+
1. Open Visual Studio Code
33+
2. Install the **Stride Shader Tools** extension:
34+
- Open Extensions view (Ctrl+Shift+X) and search for **"Stride Shader Tools"**
35+
- Or install directly from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=tebjan.sdsl) or [OpenVSX](https://open-vsx.org/extension/tebjan/sdsl) (for VSCodium and alternatives)
36+
37+
### Configuration
38+
39+
The extension automatically discovers shaders from:
40+
* Your workspace folder
41+
* Stride NuGet packages in `%NUGET_PACKAGES%` or `~/.nuget/packages`
42+
* vvvv gamma installations (for vvvv users)
43+
44+
You can add custom shader directories in VS Code settings:
45+
1. Open Settings (Ctrl+,)
46+
2. Search for "Stride Shader Tools"
47+
3. Add paths to **Additional Shader Paths**
48+
49+
## IntelliSense features
50+
51+
### Context-aware completions
52+
53+
The extension provides intelligent completions based on your current context:
54+
55+
#### Inherited members
56+
57+
When you inherit from a shader class, all inherited methods and members appear in completions:
58+
59+
```cs
60+
shader MyShader : ComputeColor
61+
{
62+
override float4 Compute()
63+
{
64+
// Type 'base.' to see all base class methods
65+
return base.Compute();
66+
}
67+
}
68+
```
69+
70+
Type `override ` to see all methods you can override from the inheritance hierarchy.
71+
72+
#### Streams
73+
74+
The extension shows available streams based on:
75+
* Current shader stage (vertex, pixel, compute)
76+
* Declared streams in the inheritance chain
77+
* Built-in Stride streams
78+
79+
```cs
80+
shader MyVertexShader : ShaderBase, Transformation
81+
{
82+
stage void VSMain()
83+
{
84+
// Type 'streams.' to see all available streams
85+
streams.Position = mul(streams.Position, World);
86+
}
87+
}
88+
```
89+
90+
#### Semantic bindings
91+
92+
After typing `:` in shader input/output declarations, the extension provides completions for valid semantics:
93+
94+
```cs
95+
shader MyShader : ShaderBase
96+
{
97+
stage stream float4 Position : SV_Position;
98+
// ^ Get completions for all valid semantics
99+
100+
stage stream float2 TexCoord : TEXCOORD0;
101+
// ^ Hover for documentation
102+
}
103+
```
104+
105+
Hover over any semantic to see:
106+
* What the semantic represents
107+
* Which shader stages it's valid in
108+
* Usage examples
109+
110+
#### Compositions
111+
112+
When declaring a composition, the extension shows all shaders that implement the required interface:
113+
114+
```cs
115+
shader MyMaterial : MaterialPixelStream
116+
{
117+
compose ComputeColor diffuseMap;
118+
// ^ Get suggestions for all ComputeColor implementations
119+
}
120+
```
121+
122+
This helps you discover compatible shaders without manually browsing files.
123+
124+
### Go-to-definition
125+
126+
Use **Ctrl+Click** (or F12) on any shader class, method, or member to jump to its definition. This works across the inheritance hierarchy:
127+
128+
* Click on a base class name → jump to base shader file
129+
* Click on an inherited method → jump to the implementation in the base class
130+
* Click on a stream → jump to where it's declared
131+
132+
Use **Alt+Left** to navigate back.
133+
134+
### Hover information
135+
136+
Hover over any identifier to see:
137+
* Type information
138+
* Method signatures
139+
* Documentation from base classes
140+
* Semantic binding explanations
141+
* Where the symbol is defined
142+
143+
## Sidebar panels
144+
145+
### Inheritance tree
146+
147+
The **Inheritance Tree** panel shows the complete hierarchy of the shader you're editing. This is particularly useful for understanding complex inheritance chains in Stride's shader system.
148+
149+
For example, when editing a material shader, you might see:
150+
```
151+
MyCustomMaterial
152+
├─ MaterialPixelShadingStream
153+
│ ├─ MaterialPixelStream
154+
│ │ └─ ShaderBase
155+
│ └─ ShadingBase
156+
└─ NormalMapTexture
157+
└─ ComputeColor
158+
```
159+
160+
Click any shader in the tree to open its source file.
161+
162+
### Member explorer
163+
164+
The **Member Explorer** panel lists all methods and variables available in your shader, including inherited members. Members are grouped by:
165+
166+
* **Methods** - All callable methods (including overridden and inherited)
167+
* **Variables** - Stage and stream variables
168+
* **Compositions** - Composition declarations
169+
170+
Each entry shows:
171+
* The member name
172+
* Its type
173+
* Which shader class it's defined in (for inherited members)
174+
* Whether it's overridable
175+
176+
Click any member to jump to its definition.
177+
178+
## Working with inheritance
179+
180+
SDSL uses multiple inheritance with specific resolution rules. The extension helps you navigate this complexity.
181+
182+
### Understanding method resolution
183+
184+
When multiple base classes define the same method, the rightmost base class wins. The inheritance tree visualizes this clearly.
185+
186+
```cs
187+
shader ShaderA : BaseA, BaseB, BaseC
188+
{
189+
// If BaseA, BaseB, and BaseC all define Compute(),
190+
// BaseC's implementation is used unless overridden here
191+
}
192+
```
193+
194+
Use the inheritance tree to see the complete chain and understand which implementation applies.
195+
196+
### Overriding methods
197+
198+
To override a method:
199+
200+
1. Type `override ` in your shader class
201+
2. Select the method you want to override from the completion list
202+
3. The method signature is automatically inserted
203+
204+
The extension shows which methods can be overridden and where they're defined in the hierarchy.
205+
206+
### Calling base implementations
207+
208+
To call the base class implementation of a method:
209+
210+
```cs
211+
shader MyShader : ComputeColor
212+
{
213+
override float4 Compute()
214+
{
215+
float4 baseColor = base.Compute();
216+
return saturate(baseColor * 2.0);
217+
}
218+
}
219+
```
220+
221+
Type `base.` to see all available base class methods.
222+
223+
## Best practices
224+
225+
### Explore before implementing
226+
227+
Before writing a shader:
228+
229+
1. Use **Go-to-Definition** to explore base classes
230+
2. Check the **Inheritance Tree** to understand the hierarchy
231+
3. Review the **Member Explorer** to see what's already available
232+
4. Decide what needs to be overridden vs reused
233+
234+
This prevents duplicate work and helps you leverage existing functionality.
235+
236+
### Use static calls instead of includes
237+
238+
SDSL allows calling static functions from other shaders without `#include`:
239+
240+
```cs
241+
shader Utils
242+
{
243+
static float4 Invert(float4 color)
244+
{
245+
return float4(1.0 - color.rgb, color.a);
246+
}
247+
}
248+
249+
shader MyShader : ComputeColor
250+
{
251+
override float4 Compute()
252+
{
253+
return Utils.Invert(base.Compute());
254+
}
255+
}
256+
```
257+
258+
The extension provides completions for static functions in all shaders in scope.
259+
260+
### Leverage hover documentation
261+
262+
When unsure about a method, semantic, or type:
263+
* Hover to see documentation
264+
* Check the signature and return type
265+
* Use **Go-to-Definition** to see the implementation
266+
267+
This reduces context-switching to external documentation.
268+
269+
## Comparison with Visual Studio
270+
271+
Both Visual Studio and VS Code are viable options for Stride shader development:
272+
273+
| Feature | VS Code + Extension | Visual Studio + Stride Extension |
274+
|---------|---------------------|----------------------------------|
275+
| Syntax highlighting | ✅ SDSL | ✅ SDSL |
276+
| Error reporting | ✅ Real-time | ✅ On save |
277+
| Code completion | ✅ Context-aware | ⚠️ Basic |
278+
| Inheritance tree | ✅ Live panel | ❌ |
279+
| Member explorer | ✅ With inheritance context | ⚠️ Basic |
280+
| Go-to-definition | ✅ Through hierarchy | ⚠️ Limited |
281+
| Hover documentation | ✅ Full | ⚠️ Limited |
282+
| Semantic documentation | ✅ | ❌ |
283+
| Game Studio integration | ⚠️ External | ✅ Built-in |
284+
| Asset reloading | ⚠️ Manual | ✅ Automatic |
285+
| Shader debugging | 🔜 RenderDoc integration | ❌ |
286+
287+
**Visual Studio** is best if you're primarily working in Game Studio and want tight integration with asset workflows.
288+
289+
**VS Code** is best for shader-focused development where understanding inheritance and having context-aware assistance is critical.
290+
291+
Many developers use both: Game Studio with Visual Studio for asset work, and VS Code for intensive shader development.
292+
293+
## Troubleshooting
294+
295+
### Extension not activating
296+
297+
The extension activates when you open a `.sdsl` file. If it doesn't activate:
298+
299+
1. Check the Output panel (View → Output) and select "Stride Shader Tools" from the dropdown
300+
2. Verify the language server is running
301+
3. Check for errors in the Output panel
302+
303+
### Completions not working
304+
305+
If IntelliSense isn't working:
306+
307+
1. Ensure the shader file is in a valid workspace folder
308+
2. Check that the file is properly formatted (no syntax errors)
309+
3. Verify the extension has discovered shader paths (check Output panel)
310+
4. Try reloading the window (Ctrl+Shift+P → "Reload Window")
311+
312+
### Inheritance tree not showing
313+
314+
The inheritance tree requires:
315+
* Valid SDSL syntax
316+
* At least one base class declared
317+
* The file to be part of the workspace
318+
319+
If the tree is empty, check for syntax errors in the file.
320+
321+
## See also
322+
323+
* [Custom shaders](custom-shaders.md) - Creating and using shaders in materials
324+
* [Shading language](shading-language/index.md) - SDSL language reference
325+
* [Shader classes, mixins and inheritance](shading-language/shader-classes-mixins-and-inheritance.md) - Inheritance concepts
326+
* [Composition](shading-language/composition.md) - Using shader compositions
327+
* [Stride Shader Explorer](https://github.com/tebjan/Stride.ShaderExplorer) - Standalone tool for browsing shader hierarchies

0 commit comments

Comments
 (0)