version: "1.0.0" name: dream-shader-migrate description: Rewrite DreamShaderLang 1.x sources (.dsm / .dsf / .dsh) as 2.0 .dss with dsc migrate, which proves each rewrite builds the same graph before it writes anything. Use when asked to migrate, upgrade, port or convert 1.x DreamShader sources, a .dsm or .dsf file, or a whole DShader tree to the 2.0 language.

dream-shader-migrate <file> | -All | -Root <name>

Turn 1.x sources into .dss without changing what they build. dsc migrate does the rewriting and the proving; this skill is the order to run it in and what to do with what it reports.

Nothing forces a migration — the legacy front end keeps building 1.x sources through the same compiler. Migrate when the user wants what only a .dss has: real expressions and control flow, #include, material instances beside the material, comments that survive dsc fmt. Full reference: `Docs/tools/migrate.md`.

Paths below are relative to the plugin root, Plugins/DreamShader/.

Do this

1 — See what will change. Every 1.x leniency the rewrite has to spell out is also a diagnostic on the 1.x source, so a check of the .dsm lists them — the legacy-rule codes DSH5275–DSH5292, warnings and infos — without writing anything:

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 check DShader/Materials/M_Foo.dsm

2 — Prove the rewrite, write nothing.

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 migrate DShader/Materials/M_Foo.dsm -Check

For a whole tree, migrate -All -Check (every 1.x source under the project's own roots, Packages/ excluded — a plugin's root is left out) or migrate -Root <name> -Check (one root, by its display name or its plugin's name). Batch: one run over many files costs one editor boot, the same as one file. (-DryRun is the same as -Check.)

A file is refused before anything is rewritten unless it builds as 1.x first. Then it is proved: no comment is lost (DSH9092) and the text builds as 2.0 (DSH9097) — either failure writes nothing. Two more checks are warnings, which do not stop the write: the graph of the new text is compared with the old one node by node (DSH9098 names the first node that differs), and the asset must keep its path — the export gets a /// @name when the file's place would name another one, and DSH9098 says so when it cannot.

3 — Read every `DSH9098`. It is not noise: each one is a real difference between the two graphs. Decide with the user whether the 2.0 behaviour is acceptable — typically it is a 1.x artefact (a node declared narrower than it is, an explicit .x into a float pin). An error stops that file; the table below says what to do.

4 — Migrate.

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 migrate DShader/Materials/M_Foo.dsm

This writes M_Foo.dss beside the old file and moves M_Foo.dsm to Saved/DreamShader/Migrated/Sources/<root>/<path> (numbered .1, .2, … rather than overwriting an older backup) — outside the source tree, and outside version control. A .dsh is rewritten in place, and stays a .dsh. -Out <dir> writes the .dss files under another directory, mirroring the tree, and leaves the 1.x files where they are: the way to look at the result first.

5 — Check the result.

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 check DShader/Materials/M_Foo.dss

check builds no asset, which is what you want here: the .dss names the same asset the .dsm did, so a compile would rewrite it on disk. The editor rebuilds it from the new source on its next load.

6 — Report the files written, the DSH9098 differences and the decision taken on each, and remind the user to commit the .dss and the deletion of the .dsm together — a commit with only one of them leaves the asset with no source, or with two.

What can stop a file

Gotchas

• A shared header waits. Migrating one file takes a header with it only when nothing else includes that

header; a shared one stays 1.x — which is fine, because a .dsh may hold both dialects. -All takes every 1.x file, headers first. A header with no 1.x declarations left is skipped (DSH9093).

• Plugin sources are not in `-All`. A plugin's source root is read-only to -All; name it with -Root.
• The old file is moved, not deleted — unless -NoBackup. It lands under Saved/, which nothing commits,

so the backup is local to this machine.

• What a `.dss` looks like afterwards is in `reference/dss.md`: Function and

GraphFunction become /// @custom functions with the body verbatim, a Namespace function N::F becomes N_F with /// @name N::F, a VirtualFunction becomes /// @asset + extern, mix / fract / mod / vec3 become lerp / frac / fmod / float3.

• A migrated file is still machine-written. It builds the same graph, which is the guarantee; making it

read like hand-written 2.0 is `dream-shader-optimize`'s job, under the same rule — behaviour must not change.

See also

• `Docs/tools/migrate.md` — the full rewrite table, rule by rule
• `Docs/language-v2/index.md` — the 2.0 language
• `dream-shader-verify` — check and compile
• `dream-shader-decompile` — for an asset that has no source at all