Workspace and editor extensions

DreamShader » Tools » Workspace and editor extensions

A generated VSCode workspace file that maps the six DreamShaderLang file extensions onto the language ids of the VS Code extension, and the editor command that writes it and launches an external editor on it.

Synopsis

<SourceDirectory>/DreamShader.code-workspace

<SourceDirectory> is the Source Directory project setting, default <Project>/DShader. The directory is created if it does not exist. The file is written UTF-8 without a BOM, pretty-printed by Unreal's JSON writer (tab indentation):

{
	"folders": [
		{
			"name": "DreamShader Source",
			"path": "."
		},
		{
			"name": "Plugin: MoonToon",
			"path": "../Plugins/MoonToon/DShader"
		}
	],
	"settings": {
		"files.associations": {
			"*.dss": "dreamshader-dss",
			"*.dsi": "dreamshader-dss",
			"*.dsp": "dreamshader-dsp",
			"*.dsm": "dreamshaderlang",
			"*.dsh": "dreamshaderlang",
			"*.dsf": "dreamshaderlang"
		}
	}
}

One folders entry per source root: the project root is always first and always "." (the workspace file lives in it), then one entry per plugin that ships a DShader folder, named Plugin: <Name> and pointed at a path relative to the workspace file. A root that has no relative form — an engine plugin on a different drive — gets its absolute path instead. See Source files.

Contents

Every key the writer emits. There are no others; only the number of folders entries varies.

Three language ids, the ones the extension registers: dreamshaderlang for the 1.x sources and headers, dreamshader-dss for 2.0 sources, dreamshader-dsp for pipelines (extension 2.1.0 and later). A workspace association overrides the extension's own mapping of an extension to a language, so the two have to agree: with dreamshaderlang for a .dss, VS Code would give it the 1.x grammar and language server. Settings scoped to a language -- "[dreamshader-dss]": { ... } -- use the same ids.

[!WARNING] The file is rewritten from scratch on every invocation of Open Dream Shader Workspace. The writer serializes a fixed object; it never reads, merges or preserves the existing file. Any launch, tasks, extensions or extra settings entries added by hand are destroyed the next time the command runs. Keep per-user workspace configuration in a different .code-workspace file or in <SourceDirectory>/.vscode/settings.json, neither of which this command touches.

Open behaviour

The command performs five steps, in this order:

Steps 1–3 are the same three manifests the bridge writes at editor startup; opening the workspace refreshes them so an extension that has just been installed sees current data without an editor restart.

Launch fallback chain

The first mechanism that succeeds wins; the rest are not attempted.

VSCode executable discovery

Probed in this exact order. Only paths that exist as files are kept, and duplicates are dropped.

There is no setting that names a VSCode executable. A non-standard install is reachable only by putting it on PATH.

The reuse-window setting

[!NOTE] bOpenInNewWindow is consulted by the workspace launcher only. Every other DreamShader action that opens a file in VSCode uses a separate launcher that always passes --reuse-window -g "<path>:<line>:<column>", regardless of the setting. Turning Open In New Window on does not make Open source, OpenVirtualFunction or the post-export open use a new window.

The file launcher clamps line and column to 1 or greater. Its own fallback chain is VSCode → shell default application (Edit verb) → Notepad, the same shape as the workspace chain.

Diagnostics

Runtime substitutions are shown as {Placeholder}. Toast text and log text differ; both are listed.

Writer errors, substituted into {Error} above:

All logging goes to the LogDreamShader category.

Editor extensions

The language tooling lives in two repositories, neither of which ships inside this plugin. The plugin contributes the workspace file, the file associations and the bridge artifacts; everything below — grammars, completion, navigation, package commands — is implemented by the extension.

Extension-side settings (for example a project-root override, a preview frame rate, or package store index URLs) are declared by the extension, not by UDreamShaderSettings, and are documented in the extension's own repository. The release workflow attaches the latest VSCode extension assets to each plugin GitHub release; see Release.

What an extension consumes

Every artifact an extension reads or writes lives under <Project>/Saved/DreamShader/Bridge/, plus the loopback WebSocket endpoint. The full schemas are on Editor bridge.

pass-keys.json

(since 2.1.0) The vocabulary of a .dsp, for an editor's completion: <Project>/Saved/DreamShader/Bridge/pass-keys.json, schema DreamShader.PassKeys, version 1, with a generatedAt timestamp. It is written with settings.json — at bridge startup and on Open Dream Shader Workspace — because the layer names it ends with are a project setting. It has no bridge.db table.

Every key entry is name, value (the kind of value, which names the list it is completed from — injection for injectionPoints, …), default (what leaving the key out means), required (true when there is no default) and detail.

Example

Running Tools ▸ DreamShader ▸ Open Dream Shader Workspace (VSCode) on a default project touches:

<Project>/DShader/DreamShader.code-workspace                    rewritten
<Project>/Saved/DreamShader/Bridge/material-expressions.json    rewritten
<Project>/Saved/DreamShader/Bridge/settings.json                rewritten
<Project>/Saved/DreamShader/Bridge/pass-keys.json               rewritten (since 2.1.0)
<Project>/Saved/DreamShader/Bridge/substrate-builtins.json      rewritten
<Project>/Saved/DreamShader/Bridge/bridge.db                    tables replaced

and then launches, for a code.cmd candidate with Open In New Window left at its default:

%ComSpec% /C ""C:/Users/<user>/AppData/Local/Programs/Microsoft VS Code/bin/code.cmd"  "C:/Projects/MyGame/DShader/DreamShader.code-workspace""

With Open In New Window turned off, the same line carries the extra flag:

%ComSpec% /C ""C:/Users/<user>/AppData/Local/Programs/Microsoft VS Code/bin/code.cmd" --reuse-window "C:/Projects/MyGame/DShader/DreamShader.code-workspace""

See also

• Editor bridge — the artifacts, request files and WebSocket protocol an extension drives
• Packages — DShader/Packages, and which half of the package system the extension owns
• Editor integration — the Tools menu and toolbar entries that invoke this command
• Material Content Browser — the Open source action that uses the file launcher
• VirtualFunction tools — OpenVirtualFunction and its line/column jump
• Decompiler — the Export entries and the post-export open
• Project settings — SourceDirectory and bOpenInNewWindow
• Source files — what .dsm, .dsh and .dsf may each contain
• Custom Pass pipelines — .dsp — the language pass-keys.json describes
• Release — how extension assets are attached to a plugin release