工作区和编辑器扩展

DreamShader » 工具 » 工作区和编辑器扩展

一个生成的 VSCode 工作区文件，它将六个 DreamShaderLang 文件扩展名映射到 VS Code 扩展 的语言 ID，以及写入该文件并在其上启动外部编辑器的编辑器命令。

概要

<SourceDirectory>/DreamShader.code-workspace

<SourceDirectory> 是 Source Directory 项目设置，默认为 <Project>/DShader。如果该目录不存在，则会创建它。文件以不带 BOM 的 UTF-8 写入，由 Unreal 的 JSON 写入器美化打印（制表符缩进）：

{
	"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"
		}
	}
}

每个源根对应一个 folders 条目：项目根始终位于第一位，并且始终为 "."（工作区文件就位于其中），然后每个附带了 DShader 文件夹的插件对应一个条目，命名为 Plugin: <Name>，并指向相对于工作区文件的路径。没有相对形式的根 — 位于不同驱动器上的引擎插件 — 则改为使用其绝对路径。请参阅源文件。

内容

写入器输出的每一个键。没有其他键；只有 folders 条目的数量会变化。

三个语言 ID，即扩展注册的那些：dreamshaderlang 用于 1.x 源和头文件，dreamshader-dss 用于 2.0 源，dreamshader-dsp 用于管线（扩展 2.1.0 及更高版本）。工作区关联会覆盖扩展自身将扩展名映射到语言的映射，因此两者必须一致：如果对 .dss 使用 dreamshaderlang，VS Code 会为它使用 1.x 语法和语言服务器。作用域为某个语言的设置——"[dreamshader-dss]": { ... }——使用相同的 ID。

[!WARNING] 每次调用 打开 Dream Shader 工作区 时，该文件都会从头重写。写入器序列化一个固定对象；它从不读取、合并或保留现有文件。任何手动添加的 launch、tasks、extensions 或额外的 settings 条目都会在该命令下次运行时被销毁。请将每用户工作区配置保存在不同的 .code-workspace 文件中或 <SourceDirectory>/.vscode/settings.json 中，此命令不会触及这两者。

打开行为

该命令按以下顺序执行五个步骤：

步骤 1–3 与 bridge 在编辑器启动时写入的三个清单相同；打开工作区会刷新它们，因此刚刚安装的扩展无需重启编辑器即可看到当前数据。

启动回退链

第一个成功的机制胜出；不会尝试其余的。

VSCode 可执行文件发现

按此确切顺序探测。仅保留作为文件存在的路径，并丢弃重复项。

没有用于指定 VSCode 可执行文件的设置。非标准安装只能通过将其放入 PATH 来访问。

重用窗口设置

[!NOTE] bOpenInNewWindow 仅由工作区启动器查询。所有其他在 VSCode 中打开文件的 DreamShader 操作都使用单独的启动器，该启动器始终传递 --reuse-window -g "<path>:<line>:<column>"，无论该设置如何。开启 Open In New Window 不会让 Open source、OpenVirtualFunction 或导出后打开使用新窗口。

文件启动器会将行和列限制为 1 或更大。其自身的回退链为 VSCode → shell 默认应用程序（Edit 谓词）→ 记事本，与工作区链形态相同。

诊断

运行时替换项显示为 {Placeholder}。提示文本和日志文本不同；两者均已列出。

写入器错误，替换到上面的 {Error} 中：

所有日志都记录到 LogDreamShader 类别。

编辑器扩展

语言工具链位于两个仓库中，两者都不随本插件提供。插件提供工作区文件、文件关联以及桥接构件；下面的一切——语法、补全、导航、包命令——都由扩展实现。

扩展端的设置（例如项目根目录覆盖、预览帧率或包存储索引 URL）由扩展声明，而非由 UDreamShaderSettings 声明，并记录在扩展自己的仓库中。发布工作流会将最新的 VSCode 扩展资源附加到每个插件 GitHub 发布中；参见发布。

扩展消费的内容

扩展读取或写入的每个构件都位于 <Project>/Saved/DreamShader/Bridge/ 下，外加回环 WebSocket 端点。完整架构参见编辑器桥接。

pass-keys.json

（自 2.1.0 起） .dsp 的词汇表，用于编辑器补全： <Project>/Saved/DreamShader/Bridge/pass-keys.json，架构 DreamShader.PassKeys，版本 1，带 generatedAt 时间戳。它使用 settings.json 写入——在桥接启动时以及 Open Dream Shader Workspace 时——因为它结尾的层名是项目设置。它没有 bridge.db 表。

每个键条目都是 name、value（值的类型，它命名补全来源的列表——injection 对应 injectionPoints，……）、default（省略该键意味着什么）、required（没有默认值时为 true）以及 detail。

示例

在默认项目上运行 Tools ▸ DreamShader ▸ Open Dream Shader Workspace (VSCode) 会触及：

<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

然后，对于一个 code.cmd 候选程序，在 Open In New Window 保持默认值的情况下，启动：

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

在关闭 Open In New Window 的情况下，同一行会带上额外标志：

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

另见

• 编辑器桥接 — 扩展所驱动的产物、请求文件和 WebSocket 协议
• 包 — DShader/Packages，以及扩展拥有包系统的哪一半
• 编辑器集成 — 调用此命令的“工具”菜单和工具栏条目
• 材质内容浏览器 — 使用文件启动器的打开源操作
• VirtualFunction 工具 — OpenVirtualFunction 及其行/列跳转
• 反编译器 — 导出条目及导出后打开
• 项目设置 — SourceDirectory 和 bOpenInNewWindow
• 源文件 — .dsm、.dsh 和 .dsf 各自可以包含的内容
• 自定义 Pass 管线 — .dsp — pass-keys.json 所描述的语言
• 发布 — 扩展资源如何附加到插件发布版本