Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(shaders): the canonical vertex stage hands a mesh second uv set to a material, and a converted effect is one shader per macro combination, compiled and given its WGSL twin before it is written

yhh73bd01a38d13
diff --git a/desktop b/desktop
index bb747d95b..0a2712b0a 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit bb747d95bfbb0183eb484804e50ea730495391ae
+Subproject commit 0a2712b0a1dd73b36e657cd2133ad6aaba237065
diff --git a/pipeline/src/import/cocos/effectConvert.ts b/pipeline/src/import/cocos/effectConvert.ts
index 0c8ff1e19..3bd7c5218 100644
--- a/pipeline/src/import/cocos/effectConvert.ts
+++ b/pipeline/src/import/cocos/effectConvert.ts
@@ -5,7 +5,8 @@
* @brief A Cocos `.effect` pass as an Estella `.esshader` and the render state of its `.esmaterial`.
*
* What carries across is what a pass says about its own fragment: the `frag()` function, the properties it reads (a `Constant` block's
- * members and its samplers, which become `#pragma param`), the macros it branches on (`#pragma switch`) and the pass's blend, depth and cull
+ * members and its samplers, which become `#pragma param`), the macros it branches on (`#pragma switch`, or `#define` when a material's own are given)
+ * and the pass's blend, depth and cull
* state. The vertex stage is the engine's own: a pass whose vertex program only applies the standard transform needs nothing of its own, which
* is the usual case (a sprite, a UI quad, an unlit mesh). A pass whose vertex program does more (a wave, a sway, an outline expansion) cannot be
* given the engine's stage and is reported, not approximated: the converted material would draw something other than what it was made to.
@@ -102,7 +103,6 @@ in highp vec3 v_worldNormal;
const PRELUDE = `// Cocos built-ins the converted fragment calls.
#define CCFragOutput(c) (c)
#define cc_time u_time
-#define CC_HANDLE_RT_SAMPLE_FLIP(uv)
vec3 LinearToSRGB(vec3 c) { return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), c)); }
vec3 SRGBToLinear(vec3 c) { return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(vec3(0.04045), c)); }
`;
@@ -111,6 +111,55 @@ vec3 SRGBToLinear(vec3 c) { return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(
* A preprocessor expression with each bare macro name asked as `defined(NAME)`: a name that is not defined is 0 in Cocos, and in GLSL ES it is an
* error. A name compared with a number (`LEVEL == 2`) is left as it is, which is the one thing a bare switch cannot say.
*/
+export function pruneUnreachable(source: string, roots: readonly string[]): string {
+ // The top-level functions: a header at brace depth 0, the span up to the brace that closes it.
+ interface Fn { name: string; start: number; end: number }
+ const functions: Fn[] = [];
+ let depth = 0;
+ let open: { name: string; start: number } | null = null;
+ const header = /(?:^|\n)[ \t]*(?:(?:highp|mediump|lowp|const|inout|in|out)\s+)*\w+(?:\[\d*\])?\s+(\w+)\s*\([^;{}]*\)\s*\{/y;
+ for (let i = 0; i < source.length; i++) {
+ const c = source[i]!;
+ if (depth === 0 && !open && (c === '\n' || i === 0)) {
+ header.lastIndex = i;
+ const m = header.exec(source);
+ if (m && !/^(?:if|for|while|switch|return)$/.test(m[1]!)) {
+ const braceAt = i + m[0].length - 1;
+ open = { name: m[1]!, start: i === 0 && source[0] !== '\n' ? 0 : i + 1 };
+ depth = 1;
+ i = braceAt;
+ continue;
+ }
+ }
+ if (c === '{') depth++;
+ else if (c === '}') {
+ depth--;
+ if (depth === 0 && open) { functions.push({ ...open, end: i + 1 }); open = null; }
+ }
+ }
+ if (functions.length === 0) return source;
+ // What the roots reach by name, through the bodies of the functions of that name (overloads share one).
+ const reached = new Set<string>(roots);
+ const byName = new Map<string, Fn[]>();
+ for (const f of functions) byName.set(f.name, [...(byName.get(f.name) ?? []), f]);
+ const queue = [...roots];
+ // A function is a root too where something outside every function names it (a macro, an initialiser).
+ const outside = functions.reduceRight((text, f) => text.slice(0, f.start) + ' ' + text.slice(f.end), source);
+ for (const name of byName.keys()) if (new RegExp(`\\b${name}\\b`).test(outside) && !reached.has(name)) { reached.add(name); queue.push(name); }
+ while (queue.length > 0) {
+ const name = queue.pop()!;
+ for (const f of byName.get(name) ?? []) {
+ for (const m of source.slice(f.start, f.end).matchAll(/\b([A-Za-z_]\w*)\s*\(/g)) {
+ const callee = m[1]!;
+ if (byName.has(callee) && !reached.has(callee)) { reached.add(callee); queue.push(callee); }
+ }
+ }
+ }
+ let out = source;
+ for (const f of [...functions].reverse()) if (!reached.has(f.name)) out = out.slice(0, f.start) + out.slice(f.end);
+ return out;
+}
+
function definedForm(expr: string): string {
const kept: string[] = [];
const guarded = expr.replace(/\bdefined\s*(?:\(\s*\w+\s*\)|\s+\w+)/g, (m) => { kept.push(m); return `\u0001${kept.length - 1}\u0001`; });
@@ -150,7 +199,7 @@ export interface EffectOptions {
}
/** Chunks of Cocos that the prelude gives (a fragment's built-ins, the scene's uniform blocks): they are left out rather than read. */
-const PROVIDED = /(?:^|\/)(?:fog-fs|output|output-standard|embedded-alpha|alpha-test|common-define|cc-global|cc-local|cc-environment|cc-forward-light|cc-shadow|gamma|aces)$/;
+const PROVIDED = /(?:^|\/)(?:fog-fs|output|output-standard|embedded-alpha|cc-global|cc-local|cc-environment|cc-forward-light|cc-shadow|gamma|aces)$/;
/** Chunks that make up Cocos's vertex input and its world matrix. The vertex stage is emulated (see below) with the prelude's version of them. */
const VERTEX_STRUCTURE = /(?:^|\/)(?:input|input-standard|decode-base|decode-standard|local-batch|fog-vs|shadow-map-vs|morph|skinning)$/;
@@ -170,7 +219,7 @@ function expandIncludes(
if (skip.test(name)) return '';
if (seen.has(name)) return '';
seen.add(name);
- const text = effect.programs.get(name)?.source ?? options.chunk?.(name) ?? null;
+ const text = (effect.programs.get(name)?.source ?? options.chunk?.(name) ?? null)?.replace(/\r\n/g, '\n') ?? null;
if (text === null) { missing.push(name); return line; }
if (depth > 12) { missing.push(`${name} (too deep)`); return line; }
return expandIncludes(text, effect, options, seen, missing, depth + 1, skip);
@@ -194,7 +243,6 @@ const VERTEX_PRELUDE = `// The vertex stage of the effect, run per fragment on w
struct StandardVertInput { highp vec4 position; vec3 normal; vec4 tangent; };
#define CCGetWorldMatrix(m) m = mat4(1.0)
#define CCGetWorldMatrixFull(m, mit) m = mat4(1.0); mit = mat4(1.0)
-#define CC_HANDLE_GET_CLIP_FLIP(p) p
#define CCVertInput(In) CCDecode(In)
void CCDecode(out StandardVertInput In) { In.position = vec4(a_position, 1.0); In.normal = a_normal; In.tangent = a_tangent; }
void CCDecode(out vec4 position) { position = vec4(a_position, 1.0); }
@@ -202,7 +250,7 @@ void CCDecode(out vec4 position) { position = vec4(a_position, 1.0); }
const ATTRIBUTE_SOURCES: Record<string, string> = {
a_position: 'cocos_position', a_normal: 'cocos_normal', a_tangent: 'cocos_tangent', a_texCoord: 'v_texCoord', a_color: 'v_color',
- a_texCoord1: 'v_texCoord', a_uv0: 'v_texCoord',
+ a_texCoord1: 'cocos_texCoord1', a_uv0: 'v_texCoord',
};
/** The attributes the vertex stage always has: declared whether or not the program says so, since the prelude's decode reads them. */
@@ -211,6 +259,14 @@ const STANDARD_ATTRIBUTES: Record<string, string> = { a_position: 'vec3', a_norm
/** The varyings the engine's vertex stage owns. */
const ENGINE_VARYING_NAMES = new Set(['v_color', 'v_texCoord', 'v_worldPos', 'v_worldXYZ', 'v_worldNormal', 'v_worldTangent']);
+/** The second uv set: the engine hands it down wherever the vertices carry one (MESH_LIGHTMAP), and a draw with none reads the first. */
+const UV1_VARYING = `#ifdef MESH_LIGHTMAP
+in highp vec2 v_texCoord1;
+#define cocos_texCoord1 v_texCoord1
+#else
+#define cocos_texCoord1 v_texCoord
+#endif`;
+
const TANGENT_VARYING = `#ifdef MESH_TANGENTS
in highp vec4 v_worldTangent;
#define cocos_tangent v_worldTangent
@@ -262,7 +318,7 @@ function emulateVertex(program: string, entry: string): Emulated | { error: stri
declared.push(`${type} ${name};`);
const source = ATTRIBUTE_SOURCES[name];
if (source) setup.push(` ${name} = ${source}${coerce(type, name)};`);
- if (name === 'a_texCoord1') approximations.push('the second uv is the first until the engine carries one');
+ if (name === 'a_texCoord1') approximations.push('the second uv is the mesh\'s own where it has one and the first uv where it has none');
}
return { source: text, attributes: declared.join('\n'), outputs, attributeSetup: setup, approximations, displaces };
}
@@ -281,12 +337,14 @@ function coerce(type: string, name: string): string {
// ---------------------------------------------------------------------------
/** Convert one pass. The effect's name is the shader's. */
-export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: string, options: EffectOptions = {}): PassConversion {
+export function convertPass(
+ effect: CocosEffect, pass: EffectPass, shaderName: string, options: EffectOptions = {}, defines?: Readonly<Record<string, number | boolean | string>>,
+): PassConversion {
const state = stateOf(pass);
const fail = (unsupported: string): PassConversion => ({ shader: null, unsupported, state });
const [fragProgram, fragEntry = 'frag'] = pass.frag.split(':');
const [vertProgram, vertEntry = 'vert'] = pass.vert.split(':');
- const programText = (name: string | undefined): string | null => (name ? effect.programs.get(name)?.source ?? options.chunk?.(name) ?? null : null);
+ const programText = (name: string | undefined): string | null => (name ? effect.programs.get(name)?.source ?? options.chunk?.(name) ?? null : null)?.replace(/\r\n/g, '\n') ?? null;
const fragSource = programText(fragProgram);
if (fragSource === null) return fail(`fragment program ${fragProgram} is not in the effect`);
// A vertex stage the Creator install supplies (`general-vs`, `legacy/main-functions/general-vs`) is the standard one: the engine's.
@@ -320,13 +378,23 @@ export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: s
if (missing.length > 0) return fail(`it includes ${[...new Set(missing)].join(', ')}, which the engine has no counterpart for`);
if (/fog-fs|fog-vs/.test(fragSource + (vertSource ?? ''))) approximations.push('fog is not applied');
+ // Macros that only Cocos's own effect compiler reads: one that carries a preprocessor directive in its body or pastes tokens (`##`) is no GLSL ES, and
+ // is left out; a pass that calls one fails to compile, and says so.
+ const portable = (text: string): string => text
+ .replace(/^[ \t]*#[ \t]*define(?:\\\n|[^\n])*/gm, (block) => (/##|\\\n[ \t]*#[ \t]*(?:if|endif|else)/.test(block) ? '' : block))
+ .replace(/^[ \t]*#[ \t]*pragma[ \t]*\/\/[^\n]*$/gm, '');
const strip = (text: string): string => text.replace(/^[ \t]*#[ \t]*pragma[ \t]+define[ \t]+(?!-meta)/gm, '#define ').replace(/^\s*#include\s*<[^>]+>\s*$/gm, '').replace(/^\s*precision\s+\w+\s+float\s*;\s*$/gm, '').replace(/^\s*#pragma\s+(?:builtin|define-meta|format)\([^)]*\)\s*$/gm, '').replace(/^\s*#pragma\s+define-meta[^\n]*$/gm, '');
- body = strip(body);
- vertexText = strip(vertexText);
+ // What a chunk declares as a macro's default (`#pragma define-meta NAME default(1)`, `options([a, r])`): the value a material that sets none has.
+ const metaDefaults = new Map<string, string>();
+ for (const m of `${body}\n${vertexText}`.matchAll(/^[ \t]*#[ \t]*pragma[ \t]+define-meta[ \t]+(\w+)[ \t]+(.*)$/gm)) {
+ const value = /\bdefault\(([^)]*)\)/.exec(m[2]!)?.[1] ?? /\boptions\(\[\s*([^,\]\s]+)/.exec(m[2]!)?.[1];
+ if (value !== undefined && !metaDefaults.has(m[1]!)) metaDefaults.set(m[1]!, value.trim());
+ }
+ body = portable(strip(body));
+ vertexText = portable(strip(vertexText));
// The Constant blocks' members become parameters, the vertex program's as well as the fragment's; the blocks go.
- const blocks = (text: string): string => text.replace(/(?:layout\s*\([^)]*\)\s*)?uniform\s+(\w+)\s*\{([\s\S]*?)\}\s*;?/g, (_m, block: string, members: string) => {
- if (block === 'AlphaTestConstants' || block === 'ALPHA_TEST_CONSTANTS') { members = 'float alphaThreshold;'; }
+ const blocks = (text: string): string => text.replace(/(?:layout\s*\([^)]*\)\s*)?uniform\s+(\w+)\s*\{([\s\S]*?)\}\s*;?/g, (_m, _block: string, members: string) => {
for (const decl of members.split(';')) {
const m = /^\s*(?:highp\s+|mediump\s+|lowp\s+)?(float|int|bool|vec2|vec3|vec4)\s+(\w+)\s*$/.exec(decl.replace(/\/\/[^\n]*/g, '').trim());
if (!m) continue;
@@ -396,6 +464,7 @@ export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: s
needed.add(POSITION_VARYING);
needed.add(NORMAL_VARYING);
needed.add(TANGENT_VARYING);
+ if (/\ba_texCoord1\b/.test(vertex.attributes)) needed.add(UV1_VARYING);
}
const usesPosition = needed.has(POSITION_VARYING);
if (usesPosition) approximations.push('v_position is the world position of the draw: the engine gives the full position to meshes with normals, and the plane position to sprites');
@@ -437,35 +506,63 @@ export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: s
}
// The camera's matrices have no value at the fragment that means the same: the emulation's matrices are the identity.
const matrices = ['cc_matView', 'cc_matProj', 'cc_matViewProj', 'cc_matWorld', 'cc_matWorldIT', 'cc_matViewInv'].filter((m) => new RegExp(`\\b${m}\\b`).test(everything));
+ const everyText = `${body}\n${vertexText}`;
+ // Cocos's helper macros: the install's own where its common-define is included, these where it is not.
+ const flipFallback = Object.entries({ CC_HANDLE_RT_SAMPLE_FLIP: '(uv)', CC_HANDLE_GET_CLIP_FLIP: '(p) p' })
+ .filter(([name]) => new RegExp(`\\b${name}\\s*\\(`).test(everyText) && !new RegExp(`#define\\s+${name}\\b`).test(everyText))
+ .map(([name, tail]) => `#define ${name}${tail}\n`).join('');
const matrixDefs = matrices.map((m) => `#define ${m} mat4(1.0)`).join('\n');
- // Alpha test: a parameter and a discard, behind the switch the effect uses.
- let alphaTest = '';
- if (/\bALPHA_TEST\s*\(/.test(body)) {
- if (!declared.has('alphaThreshold')) { declared.add('alphaThreshold'); params.push({ name: 'alphaThreshold', type: 'float', value: [0.5] }); }
- alphaTest = '#define ALPHA_TEST(c) if ((c).a < alphaThreshold) discard;';
- }
-
// The entry: `vec4 frag()` is the fragment's colour.
const entry = new RegExp(`\\bvec4\\s+${fragEntry}\\s*\\(\\s*\\)`);
if (!entry.test(body)) return fail(`the fragment entry ${fragEntry}() is not there`);
body = body.replace(entry, 'vec4 cocos_frag()');
+ // A function nothing reaches (a variant of the entry this pass does not name) may read what the pass never declares, which a compiler refuses.
+ body = pruneUnreachable(body, ['cocos_frag']);
+ if (vertex) vertexText = pruneUnreachable(vertexText, ['cocos_vert']);
// Cocos reads a macro that is not defined as 0 in `#if`; GLSL ES refuses an undefined name there. A switch is defined when it is on.
const definedFormed = (text: string): string => text.replace(/^([ \t]*#[ \t]*(?:el)?if)([ \t]+.*)$/gm, (_m, directive: string, expr: string) => `${directive}${definedForm(expr)}`);
body = definedFormed(body);
vertexText = definedFormed(vertexText);
- // Macros: what the code branches on is a switch a material turns on.
+ // Macros: what the code branches on. A material fixes them (its `defines`), so given those they are baked into the shader as `#define`s and it
+ // has no switches: one shader per combination a project uses, which is the same set of programs and a shader that can be given a WGSL twin
+ // (a twin carries a body for every combination of what is left to toggle). Without them they are switches a material turns on.
const found = macrosIn(`${vertexText}\n${body}`);
- const switches = found.switches.filter((s) => !/^(MESH_NORMALS|MESH_TANGENTS|GL_ES|CC_[A-Z_]+_ENABLED)$/.test(s) && !found.compared.includes(s));
- if (found.compared.length > 0) approximations.push(`${found.compared.join(', ')} is compared to a number; the engine's switches are on or off`);
+ const ENGINE_FEATURE = /^(?:MESH_NORMALS|MESH_TANGENTS|MESH_LIGHTMAP|GL_ES|CC_[A-Z_]+_ENABLED)$/;
+ const named = found.switches.filter((m) => !ENGINE_FEATURE.test(m) && !found.compared.includes(m));
+ const compared = found.compared.filter((m) => !ENGINE_FEATURE.test(m));
+ let switches: string[] = [];
+ const baked: string[] = [];
+ if (defines) {
+ const value = { ...Object.fromEntries(metaDefaults), ...pass.macros, ...defines } as Record<string, unknown>;
+ // What the code branches on, and what it merely reads (a channel name a material gives).
+ const text = `${vertexText}
+${body}`;
+ const used = Object.keys(value).filter((k) => new RegExp(`\b${k}\b`).test(text));
+ for (const m of new Set([...named, ...compared, ...used])) {
+ const v = value[m];
+ // Zero is the undefined of Cocos's `#if`, so a name that is not compared is left undefined for it.
+ if (typeof v === 'string') { if (v !== '0' || compared.includes(m)) baked.push(`#define ${m} ${v}`); continue; }
+ const n = typeof v === 'number' ? v : v === true ? 1 : 0;
+ // A name asked as a number has to be defined; a name asked as a switch is defined when it is on.
+ if (compared.includes(m) || n !== 0) baked.push(`#define ${m} ${n}`);
+ }
+ } else {
+ switches = named;
+ if (compared.length > 0) approximations.push(`${compared.join(', ')} is compared to a number; the engine's switches are on or off`);
+ }
+ // What the engine's vertex stage offers a fragment, which the shader asks for by name so that a twin carries a body for each.
+ const offered = ['MESH_NORMALS', 'MESH_TANGENTS', 'MESH_LIGHTMAP']
+ .filter((f) => new RegExp(`\\b${f}\\b`).test(`${[...needed].join('\n')}\n${vertexText}\n${body}`));
const lines: string[] = [
`#pragma shader "${shaderName}"`,
'#pragma version 300 es',
usesPosition ? '#pragma domain Lit' : '#pragma domain Unlit',
];
+ for (const f of offered) lines.push(`#pragma feature ${f}`);
for (const s of switches) lines.push(`#pragma switch ${s} default(${pass.macros[s] ? 'on' : 'off'})`);
for (const p of params) {
lines.push(p.type === 'texture'
@@ -475,9 +572,9 @@ export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: s
const main = ['void main() {'];
if (vertex) main.push(...vertex.attributeSetup, ' cocos_vert();');
main.push(' fragColor = cocos_frag();', '}');
- lines.push('', '#pragma fragment', 'precision mediump float;', '', ...[...needed].filter((n) => !n.startsWith('/*')), '',
+ lines.push('', '#pragma fragment', 'precision mediump float;', ...baked, '', ...[...needed].filter((n) => !n.startsWith('/*')), '',
...(usesSpriteTexture ? ['uniform sampler2D u_textures[8];'] : []), 'out vec4 fragColor;', '', PRELUDE,
- ...(matrixDefs ? [matrixDefs, ''] : []), ...(alphaTest ? [alphaTest, ''] : []),
+ ...(matrixDefs ? [matrixDefs, ''] : []), ...(flipFallback ? [flipFallback] : []),
...(vertex ? [vertex.attributes, VERTEX_PRELUDE, vertexText.trim(), ''] : []), body.trim(), '', ...main, '#pragma end', '');
// The displacement, given to the engine as the material's vertex hook: the same program, run on the vertex's own position and normal. The engine's
// vertex stage owns the attribute names, so the program's are its own here.
@@ -490,6 +587,7 @@ export function convertPass(effect: CocosEffect, pass: EffectPass, shaderName: s
const extra = [...vertex.attributes.matchAll(/\ba_(texCoord1|uv0)\b/g)].map((m) => ` hook_a_${m[1]} = uv;`);
const hook = [
'#pragma vertexoffset',
+ ...baked,
'#define cc_time u_time',
...(matrixDefs ? [matrixDefs] : []),
own(vertex.attributes), own(VERTEX_PRELUDE), own(vertexText.trim()), '',
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index b20fb1713..fb1264543 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -11,6 +11,7 @@
import { createHash } from 'node:crypto';
import { copyFileSync, existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
import path from 'node:path';
+import { pathToFileURL } from 'node:url';
import { isInsideRoot } from '../../fs/pathSandbox';
import { buildScriptIndex } from './scripts';
import { buildCocosAssetIndex, cocosEditorAssets, INTERNAL_FOLDER, type CocosAssetEntry, type CocosAssetIndex } from './assets';
@@ -22,15 +23,15 @@ import { CocosModels, clipOf, clipPlayOf, mintSidecar, retargetClip } from './mo
import { convertAnimationClip } from './animationClip';
import { convertAnimationGraph } from './animationGraph';
import type { MaterialInfo } from './components';
-import { parseEffect } from './effects';
-import { convertEffect, isOutlinePass, type PassConversion } from './effectConvert';
+import { parseEffect, type CocosEffect, type EffectPass } from './effects';
+import { convertPass, isOutlinePass, type PassConversion } from './effectConvert';
/**
* The revision of what an import writes. It is recorded in the state file; a converted project whose record is older was written by an
* importer that made less (or differently), and is brought up to date when it is opened. Raise it when the converted output changes in a
* way an existing project needs to pick up: a new generated file, a field a document or a manifest now carries.
*/
-export const COCOS_IMPORT_REVISION = 5;
+export const COCOS_IMPORT_REVISION = 6;
/** Whether the project at @p projectRoot was written by an importer of this revision. A project that was not converted has nothing to bring up. */
export function cocosImportIsCurrent(projectRoot: string): boolean {
@@ -59,7 +60,7 @@ export interface CocosImportOptions {
/** Where an import is: the step it is in and how many of that step's items are done. */
export interface CocosImportProgress {
- stage: 'index' | 'prefabs' | 'scenes' | 'textures' | 'finish';
+ stage: 'index' | 'shaders' | 'prefabs' | 'scenes' | 'textures' | 'finish';
done: number;
total: number;
/** The document or asset being worked on, when there is one. */
@@ -171,6 +172,48 @@ function startSceneOf(scenes: readonly string[]): string | undefined {
return find(/(^|\/)launch\/main\.scene$/) ?? find(/(^|\/)launch\/[^/]+\.scene$/) ?? find(/^main\.scene$/);
}
+/**
+ * The engine's shader tools as a check on one converted shader: it compiles every combination of what the shader leaves to toggle, in GLSL (glslang)
+ * and as the WGSL twin the WebGPU backend runs. Null where the tools are not here (anywhere but a checkout of the engine with a built wasm), and the
+ * conversion then goes unchecked. The module is named by a path held in a variable so that the bundlers leave it and its wasm alone.
+ */
+let shaderChecking: Promise<((source: string) => Promise<string | null>) | null> | undefined;
+function shaderChecker(): Promise<((source: string) => Promise<string | null>) | null> {
+ shaderChecking ??= (async () => {
+ try {
+ // Beside the package when it runs from source, or from the bin that started a bundled run of it (the command line bundles the importer into a
+ // temporary folder), or where ESTELLA_TOOLS says.
+ const candidates = [
+ '../../../../tools/gen-shader-twins.mjs',
+ ...(process.argv[1] ? [pathToFileURL(path.resolve(path.dirname(process.argv[1]), '..', '..', 'tools', 'gen-shader-twins.mjs')).href] : []),
+ ...(process.env.ESTELLA_TOOLS ? [pathToFileURL(path.join(process.env.ESTELLA_TOOLS, 'gen-shader-twins.mjs')).href] : []),
+ ];
+ let loaded: unknown = null;
+ for (const specifier of candidates) {
+ try { loaded = await import(/* @vite-ignore */ specifier); break; } catch { /* the next */ }
+ }
+ if (!loaded) return null;
+ const tool = loaded as {
+ loadTwinModule(): Promise<unknown>;
+ deriveTwin(module: unknown, source: string, opts: object): Promise<{ status: string }>;
+ };
+ const module = await tool.loadTwinModule();
+ return async (source: string) => {
+ try {
+ const derived = await tool.deriveTwin(module, source, {});
+ // More toggles than a twin may carry is no error of the shader's: it runs on WebGL.
+ return derived.status === 'generated' || derived.status === 'has-twin' || derived.status.startsWith('skipped') ? null : derived.status;
+ } catch (err) {
+ return String((err as Error).message ?? err).split('\n').filter((l) => /ERROR|error|failed/.test(l)).slice(0, 2).join(' ').trim().slice(0, 240) || 'it could not be translated';
+ }
+ };
+ } catch {
+ return null;
+ }
+ })();
+ return shaderChecking;
+}
+
/** The design resolution a Cocos project declares, which is the box its screen-pinned roots are placed in. */
function designSizeOf(source: string): { width: number; height: number } | undefined {
try {
@@ -631,51 +674,113 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
const chunkText = (name: string): string | null => {
const own = projectChunks.find((e) => { const rel = e.rel.replace(/\.chunk$/, ''); return rel === name || rel.endsWith(`/${name}`); });
if (own) return readFileSync(own.file, 'utf8');
- const installed = editorAssets ? path.join(editorAssets, 'chunks', `${name}.chunk`) : null;
- return installed && existsSync(installed) ? readFileSync(installed, 'utf8') : null;
+ // A bare name is one of the install's own, which Cocos finds by where it keeps them.
+ const places = name.includes('/') ? [''] : ['', 'builtin/internal/', 'builtin/', 'common/', 'legacy/'];
+ for (const place of places) {
+ const installed = editorAssets ? path.join(editorAssets, 'chunks', `${place}${name}.chunk`) : null;
+ if (installed && existsSync(installed)) return readFileSync(installed, 'utf8');
+ }
+ return null;
};
- type EffectTechnique = { name: string; passes: PassConversion[]; passCount: number; outline: boolean[] };
- const effects = new Map<string, EffectTechnique[] | null>();
+ type EffectTechnique = { name: string; passes: EffectPass[]; outline: boolean[] };
+ type ParsedEffect = { effect: CocosEffect; techniques: EffectTechnique[] };
+ const effects = new Map<string, ParsedEffect | null>();
const convertedMaterials = new Map<string, { ref: string } | null>();
- const effectOf = (entry: CocosAssetEntry): EffectTechnique[] | null => {
+ const effectOf = (entry: CocosAssetEntry): ParsedEffect | null => {
if (effects.has(entry.file)) return effects.get(entry.file) ?? null;
- let result: EffectTechnique[] | null = null;
+ let result: ParsedEffect | null = null;
try {
- const parsed = parseEffect(readFileSync(entry.file, 'utf8'));
- const stem = entry.rel.replace(/^assets\//, '').replace(/\.effect$/, '');
- result = convertEffect(parsed, stem, { chunk: chunkText }).techniques.map((t, i) => ({ name: t.name, passes: t.passes, passCount: t.passes.length, outline: parsed.techniques[i]!.passes.map(isOutlinePass) }));
+ const effect = parseEffect(readFileSync(entry.file, 'utf8'));
+ result = { effect, techniques: effect.techniques.map((t) => ({ name: t.name, passes: t.passes, outline: t.passes.map(isOutlinePass) })) };
} catch (err) {
report.note('effect-unreadable', `${entry.rel}: ${(err as Error).message.split('\n')[0]}`);
}
effects.set(entry.file, result);
return result;
};
+ // One shader for each combination of macros a project's materials use of a pass: the macros are baked in, so a shader has nothing left to switch.
+ const shaders = new Map<string, PassConversion & { rel: string }>();
+ const shaderFor = (entry: CocosAssetEntry, parsed: ParsedEffect, techIndex: number, passIndex: number, defines: Record<string, number | boolean | string>): PassConversion & { rel: string } => {
+ const key = `${entry.file}|${techIndex}|${passIndex}|${JSON.stringify(Object.entries(defines).sort())}`;
+ const hit = shaders.get(key);
+ if (hit) return hit;
+ const technique = parsed.techniques[techIndex]!;
+ const stem = entry.rel.replace(/^assets\//, '').replace(/\.effect$/, '');
+ const variant = Object.keys(defines).length === 0 ? '' : `.${createHash('sha1').update(JSON.stringify(Object.entries(defines).sort())).digest('hex').slice(0, 8)}`;
+ const rel = outRef(`effects/${stem}.${technique.name}.${passIndex}${variant}.esshader`);
+ const converted = convertPass(parsed.effect, technique.passes[passIndex]!, `${stem}.${technique.name}.${passIndex}${variant}`, { chunk: chunkText }, defines);
+ const error = refused.get(rel);
+ const result = error ? { shader: null, unsupported: `the converted shader does not compile: ${error}`, state: converted.state, rel } : { ...converted, rel };
+ shaders.set(key, result);
+ return result;
+ };
const FACTORS: Record<number, string> = { 0: 'zero', 1: 'one', 2: 'src_alpha', 3: 'dst_alpha', 4: 'one_minus_src_alpha', 5: 'one_minus_dst_alpha', 6: 'src_color', 7: 'dst_color', 8: 'one_minus_src_color', 9: 'one_minus_dst_color' };
const numberOf = (x: unknown, d: number): number => (typeof x === 'number' && Number.isFinite(x) ? x : d);
+ type MaterialJson = {
+ _effectAsset?: { __uuid__?: string }; _techIdx?: number;
+ _defines?: Array<Record<string, unknown>>; _props?: Array<Record<string, unknown>>;
+ _states?: Array<{ blendState?: { targets?: Array<{ blend?: boolean; blendSrc?: number; blendDst?: number }> }; rasterizerState?: { cullMode?: number }; depthStencilState?: { depthTest?: boolean; depthWrite?: boolean } }>;
+ };
+ /** Which pass of which effect a material is drawn with, and the macros it fixes for it; null for a material of a built-in effect or of none. */
+ const planOf = (mat: CocosAssetEntry) => {
+ const json = JSON.parse(readFileSync(mat.file, 'utf8')) as MaterialJson;
+ // the engine's own look-alikes of Cocos's built-in effects are what a built-in effect becomes, as before
+ const effectEntry = BUILTIN_EFFECTS.has(json._effectAsset?.__uuid__ ?? '') ? undefined : index.byUuid.get(json._effectAsset?.__uuid__ ?? '');
+ const parsed = effectEntry && effectEntry.rel.endsWith('.effect') ? effectOf(effectEntry) : null;
+ const techIndex = json._techIdx ?? 0;
+ const technique = parsed?.techniques[techIndex];
+ // The pass that is the surface: the first that is not an outline, which is where a material's own settings are (its arrays run by pass).
+ const passIndex = technique ? Math.max(0, technique.outline.findIndex((o) => !o)) : 0;
+ const defines: Record<string, number | boolean | string> = {};
+ for (const [name, v] of Object.entries(json._defines?.[passIndex] ?? json._defines?.[0] ?? {})) {
+ if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'string') defines[name] = v;
+ }
+ return { json, effectEntry, parsed, techIndex, technique, passIndex, defines };
+ };
+ /**
+ * Whether each converted shader compiles, found out ahead of the conversion where the engine's shader tools are here (a checkout of the engine, which
+ * the cook uses as well): glslang reads every combination the shader can take. A pass whose converted fragment does not is reported as not converted, so
+ * that no material is written that names a shader the engine would refuse.
+ */
+ const refused = new Map<string, string>();
+ const checkShaders = async (): Promise<void> => {
+ const check = await shaderChecker();
+ if (!check) return;
+ const seen = new Set<string>();
+ for (const mat of index.byUuid.values()) {
+ if (!mat.rel.endsWith('.mtl') || !wanted(mat.rel)) continue;
+ try {
+ const plan = planOf(mat);
+ if (!plan.effectEntry || !plan.parsed || !plan.technique?.passes[plan.passIndex]) continue;
+ const shader = shaderFor(plan.effectEntry, plan.parsed, plan.techIndex, plan.passIndex, plan.defines);
+ if (!shader.shader || seen.has(shader.rel)) continue;
+ seen.add(shader.rel);
+ const error = await check(shader.shader.source);
+ if (error) {
+ refused.set(shader.rel, error);
+ if (process.env.COCOS_IMPORT_TRACE_DIR) writeOut(path.join(process.env.COCOS_IMPORT_TRACE_DIR, path.basename(shader.rel)), shader.shader.source);
+ }
+ } catch { /* a material that cannot be read is dealt with when it is converted */ }
+ }
+ // what was converted before the check is converted again with its answer
+ shaders.clear();
+ };
const convertedMaterial = (materialUuid: string): { ref: string } | null => {
if (convertedMaterials.has(materialUuid)) return convertedMaterials.get(materialUuid) ?? null;
let result: { ref: string } | null = null;
try {
const mat = index.byUuid.get(materialUuid);
if (mat && mat.rel.endsWith('.mtl')) {
- const json = JSON.parse(readFileSync(mat.file, 'utf8')) as {
- _effectAsset?: { __uuid__?: string }; _techIdx?: number;
- _defines?: Array<Record<string, unknown>>; _props?: Array<Record<string, unknown>>;
- _states?: Array<{ blendState?: { targets?: Array<{ blend?: boolean; blendSrc?: number; blendDst?: number }> }; rasterizerState?: { cullMode?: number }; depthStencilState?: { depthTest?: boolean; depthWrite?: boolean } }>;
- };
- // the engine's own look-alikes of Cocos's built-in effects are what a built-in effect becomes, as before
- const effectEntry = BUILTIN_EFFECTS.has(json._effectAsset?.__uuid__ ?? '') ? undefined : index.byUuid.get(json._effectAsset?.__uuid__ ?? '');
- const technique = effectEntry && effectEntry.rel.endsWith('.effect') ? effectOf(effectEntry)?.[json._techIdx ?? 0] : undefined;
- // The pass that is the surface: the first that is not an outline, which is where a material's own settings are (its arrays run by pass).
- const passIndex = technique ? Math.max(0, technique.outline.findIndex((o) => !o)) : 0;
- const pass = technique?.passes[passIndex];
+ const { json, effectEntry, parsed, techIndex, technique, passIndex, defines } = planOf(mat);
+ const pass = parsed && technique?.passes[passIndex] ? shaderFor(effectEntry!, parsed, techIndex, passIndex, defines) : null;
if (effectEntry && technique && pass) {
if (!pass.shader) {
report.note('effect-not-converted', `${effectEntry.rel}: ${pass.unsupported}`);
+ if (process.env.COCOS_IMPORT_TRACE) console.log(`[effect] ${effectEntry.rel} (${technique.name}): ${pass.unsupported}`);
} else {
- if (technique.passCount > 1) report.note('effect-extra-passes', `${effectEntry.rel} (${technique.name}): only pass ${passIndex} is drawn${technique.outline.some(Boolean) ? ' (its outline is not)' : ''}`);
+ if (technique.passes.length > 1) report.note('effect-extra-passes', `${effectEntry.rel} (${technique.name}): only pass ${passIndex} is drawn${technique.outline.some(Boolean) ? ' (its outline is not)' : ''}`);
for (const a of pass.shader.approximations) report.note('effect-approximated', `${effectEntry.rel}: ${a}`);
- const shaderRel = outRef(`effects/${effectEntry.rel.replace(/^assets\//, '').replace(/\.effect$/, '')}.${technique.name}.${passIndex}.esshader`);
+ const shaderRel = pass.rel;
writeText(shaderRel, pass.shader.source);
const materialRel = outRef(`materials/${mat.rel.replace(/^assets\//, '').replace(/\.mtl$/, '')}.esmaterial`);
const props = (json._props?.[passIndex] ?? json._props?.[0] ?? {}) as Record<string, unknown>;
@@ -701,8 +806,6 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
}
}
}
- const switches: Record<string, boolean> = {};
- for (const [name, on] of Object.entries(json._defines?.[passIndex] ?? json._defines?.[0] ?? {})) if (pass.shader.switches.includes(name) && on) switches[name] = true;
const state = json._states?.[passIndex] ?? json._states?.[0];
const target = state?.blendState?.targets?.[0];
let blendMode = pass.state.blendMode;
@@ -719,7 +822,6 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
depthTest: state?.depthStencilState?.depthTest ?? pass.state.depthTest,
depthWrite: state?.depthStencilState?.depthWrite ?? pass.state.depthWrite,
cull: cull === undefined ? pass.state.cull : cull === 0 ? 0 : cull === 1 ? 2 : 1,
- ...(Object.keys(switches).length > 0 ? { switches } : {}),
properties,
});
report.note('effect-converted', `${effectEntry.rel} (${technique.name})`);
@@ -776,7 +878,9 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
})();
const digest = (text: string): string => createHash('sha1').update(text).digest('hex');
const write = (relPath: string, json: unknown): void => writeText(relPath, `${JSON.stringify(json, null, 2)}\n`);
+ const touched = new Set<string>();
function writeText(relPath: string, text: string): void {
+ touched.add(relPath);
const file = path.join(out, relPath);
const next = digest(text);
const now = existsSync(file) ? digest(readFileSync(file, 'utf8')) : null;
@@ -825,6 +929,8 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
write(outRef('resources.json'), manifest);
}
+ progress('shaders', 0, 1);
+ await checkShaders();
for (let i = 0; i < pending.length; i++) {
const r = pending[i]!;
const e = byRel.get(r);
@@ -920,6 +1026,20 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
writeOut(`${dest}.meta`, `${JSON.stringify({ uuid: entry.uuid, version: '2.0', type: 'texture', importer: { sliceBorder: slice } }, null, 2)}\n`);
}
}
+ // The shaders and materials of an earlier import that this one did not write are the effects' own leftovers (a combination of macros no material
+ // uses now, a material that was deleted): taken away while they are still what the importer wrote, kept once the creator has edited them.
+ for (const rel of Object.keys(written)) {
+ if (touched.has(rel) || !new RegExp(`^assets/${into}/(?:effects|materials)/`).test(rel)) continue;
+ const file = path.join(out, rel);
+ if (existsSync(file) && digest(readFileSync(file, 'utf8')) === written[rel]) {
+ rmSync(file, { force: true });
+ rmSync(`${file}.meta`, { force: true });
+ report.note('effect-stale-removed', rel);
+ delete written[rel];
+ } else if (!existsSync(file)) {
+ delete written[rel];
+ }
+ }
progress('finish', 0, 1);
writeOut(stateFile, `${JSON.stringify({ revision: COCOS_IMPORT_REVISION, source, documents: written }, null, 2)}\n`);
writeOut(path.join(out, 'assets', into, 'import-report.json'), `${JSON.stringify(report.toJSON(), null, 2)}\n`);
diff --git a/pipeline/tests/cocos-effect-convert.test.ts b/pipeline/tests/cocos-effect-convert.test.ts
index 9a054215f..d33f40081 100644
--- a/pipeline/tests/cocos-effect-convert.test.ts
+++ b/pipeline/tests/cocos-effect-convert.test.ts
@@ -6,7 +6,7 @@
*/
import { describe, expect, it } from 'vitest';
import { parseEffect, describeEffect } from '../src/import/cocos/effects';
-import { convertEffect } from '../src/import/cocos/effectConvert';
+import { convertEffect, convertPass, pruneUnreachable } from '../src/import/cocos/effectConvert';
const SPRITE_ADD = `
CCEffect %{
@@ -65,6 +65,22 @@ CCProgram sprite-fs %{
}%
`;
+// The Creator install's own chunk, which a project has no copy of: the alpha test applies only where the effect switches USE_ALPHA_TEST on.
+const ALPHA_TEST_CHUNK = `
+#if USE_ALPHA_TEST
+ uniform ALPHA_TEST_DATA {
+ float alphaThreshold;
+ };
+#endif
+void ALPHA_TEST (in vec4 color) {
+ #if USE_ALPHA_TEST
+ if (color.a < alphaThreshold) discard;
+ #endif
+}
+`;
+const chunk = (name: string): string | null => (name === 'builtin/internal/alpha-test' ? ALPHA_TEST_CHUNK : null);
+const convertWithChunks = (effect: ReturnType<typeof parseEffect>, stem: string) => convertEffect(effect, stem, { chunk });
+
describe('reading an effect', () => {
it('reads its techniques, passes and properties, and its programs', () => {
const effect = parseEffect(SPRITE_ADD);
@@ -85,7 +101,7 @@ describe('reading an effect', () => {
});
describe('converting a pass', () => {
- const pass = convertEffect(parseEffect(SPRITE_ADD), 'sprite-add').techniques[0]!.passes[0]!;
+ const pass = convertWithChunks(parseEffect(SPRITE_ADD), 'sprite-add').techniques[0]!.passes[0]!;
it('turns the Constant block and the samplers into parameters, with the effect\'s defaults', () => {
expect(pass.unsupported).toBeNull();
@@ -107,16 +123,31 @@ describe('converting a pass', () => {
});
it('makes the macros it branches on switches, asked as defined() because an undefined name is an error in GLSL ES', () => {
- expect(pass.shader!.switches).toEqual(['USE_GLOW', 'USE_TINT']);
+ expect(pass.shader!.switches).toEqual(['USE_ALPHA_TEST', 'USE_GLOW', 'USE_TINT']);
const source = pass.shader!.source;
expect(source).toContain('#pragma switch USE_GLOW default(off)');
expect(source).toContain('#if defined(USE_GLOW)');
expect(source).toContain('#if !defined(USE_GLOW) && defined(USE_TINT)');
});
- it('gives the alpha test its threshold as a parameter', () => {
- expect(pass.shader!.source).toContain('#pragma param alphaThreshold float default(0.5)');
- expect(pass.shader!.source).toContain('#define ALPHA_TEST(c) if ((c).a < alphaThreshold) discard;');
+ it('reads the alpha test from the install chunk, so it applies only where the effect switches it on', () => {
+ const source = pass.shader!.source;
+ expect(source).toContain('#pragma param alphaThreshold float default(0.5)');
+ expect(source).toContain('#if defined(USE_ALPHA_TEST)');
+ expect(source).toContain('void ALPHA_TEST (in vec4 color)');
+ expect(source).not.toContain('#define ALPHA_TEST(c)');
+ });
+
+ it('has no switches when a material fixes its macros: they are baked in, and what is off is not defined', () => {
+ const effect = parseEffect(SPRITE_ADD);
+ const baked = convertPass(effect, effect.techniques[0]!.passes[0]!, 'baked', { chunk }, { USE_GLOW: true, USE_TINT: false });
+ expect(baked.unsupported).toBeNull();
+ const source = baked.shader!.source;
+ expect(baked.shader!.switches).toEqual([]);
+ expect(source).not.toContain('#pragma switch');
+ expect(source).toContain('#define USE_GLOW 1');
+ expect(source).not.toContain('#define USE_TINT');
+ expect(source).not.toContain('#define USE_ALPHA_TEST');
});
it('maps the pass\'s blend, depth and cull state', () => {
@@ -128,7 +159,8 @@ describe('a pass whose vertex program does more than place the vertex', () => {
const SWAY = SPRITE_ADD.replace('vec4 pos = cc_matViewProj * vec4(a_position, 1);', 'vec4 pos = cc_matViewProj * vec4(a_position + vec3(sin(cc_time.x), 0, 0), 1);');
it('is converted with its displacement as the material vertex hook, and that hook translates for WebGPU as well', async () => {
- const swayed = convertEffect(parseEffect(SWAY), 'sway').techniques[0]!.passes[0]!;
+ const effect = parseEffect(SWAY);
+ const swayed = convertPass(effect, effect.techniques[0]!.passes[0]!, 'sway', { chunk }, {});
expect(swayed.unsupported).toBeNull();
const source = swayed.shader!.source;
expect(source).toContain('#pragma vertexoffset');
@@ -153,15 +185,39 @@ describe('a pass whose vertex program does more than place the vertex', () => {
it('is not converted when its vertex program skins the mesh', () => {
const skinned = SPRITE_ADD.replace('in vec4 a_color;', 'in vec4 a_color;\n in vec4 a_joints;');
- const converted = convertEffect(parseEffect(skinned), 'skin').techniques[0]!.passes[0]!;
+ const converted = convertWithChunks(parseEffect(skinned), 'skin').techniques[0]!.passes[0]!;
expect(converted.shader).toBeNull();
expect(converted.unsupported).toMatch(/a_joints|skins/);
});
it('is not converted when its fragment reads something the vertex stage does not supply', () => {
const odd = SPRITE_ADD.replace('in vec2 uv0;\n uniform sampler2D', 'in vec2 uv0;\n in vec3 v_barycentric;\n uniform sampler2D');
- const converted = convertEffect(parseEffect(odd), 'odd').techniques[0]!.passes[0]!;
+ const converted = convertWithChunks(parseEffect(odd), 'odd').techniques[0]!.passes[0]!;
expect(converted.shader).toBeNull();
expect(converted.unsupported).toContain('v_barycentric');
});
});
+
+describe('what an entry does not reach', () => {
+ it('is dropped, so a function of another entry that reads what this pass never declares cannot stop the shader', () => {
+ const source = [
+ 'uniform float k;',
+ 'float helper(float x) { return x * k; }',
+ 'vec4 other() { return vec4(undeclaredName); }',
+ 'vec4 cocos_frag() {',
+ ' if (k > 0.0) { return vec4(helper(1.0)); }',
+ ' return vec4(0.0);',
+ '}',
+ ].join('\n');
+ const pruned = pruneUnreachable(source, ['cocos_frag']);
+ expect(pruned).toContain('float helper(float x)');
+ expect(pruned).toContain('vec4 cocos_frag()');
+ expect(pruned).not.toContain('undeclaredName');
+ expect(pruned).toContain('uniform float k;');
+ });
+
+ it('keeps what a macro or a declaration outside the functions names', () => {
+ const source = ['float a() { return 1.0; }', '#define USE_A a()', 'vec4 cocos_frag() { return vec4(USE_A); }'].join('\n');
+ expect(pruneUnreachable(source, ['cocos_frag'])).toContain('float a()');
+ });
+});
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 5cc276360..e5cbff357 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -272,6 +272,9 @@ std::string wgslCanonicalVSOut(bool lit) {
// is the material's, as all of its shading is.
"#ifdef MESH_LIGHTMAP\n"
" @location(5) v_lightmap : vec3f,\n"
+ // The mesh's own second uv set, as authored: what a material that is not a bake reads it for (a mask, a dissolve map). The vertices carry it
+ // whenever MESH_LIGHTMAP is on, which is what that feature says.
+ " @location(9) v_texCoord1 : vec2f,\n"
"#endif\n";
if (lit) {
// Which run of coefficients this instance reads. Flat: an index, not a
@@ -429,6 +432,7 @@ std::string canonicalVertexStageWGSL(bool lit, const std::string& hook = {}) {
" let lmRect = esInstanceLightmapRect();\n"
" out.v_lightmap = vec3f(v.a_texCoord1 * lmRect.xy + lmRect.zw,\n"
" select(0.0, 1.0, lmRect.x > 0.0));\n"
+ " out.v_texCoord1 = v.a_texCoord1;\n"
"#endif\n";
if (lit) {
src += " out.v_worldPos = world.xy;\n";
@@ -577,6 +581,7 @@ std::string canonicalVertexStage(bool lit, const std::string& hook = {}) {
"#endif\n"
"#ifdef MESH_LIGHTMAP\n"
"out highp vec3 v_lightmap;\n"
+ "out highp vec2 v_texCoord1;\n"
"#endif\n";
if (lit) {
src += "out highp vec2 v_worldPos;\n";
@@ -662,6 +667,7 @@ std::string canonicalVertexStage(bool lit, const std::string& hook = {}) {
" highp vec4 lmRect = esInstanceLightmapRect();\n"
" v_lightmap = vec3(a_texCoord1 * lmRect.xy + lmRect.zw,\n"
" lmRect.x > 0.0 ? 1.0 : 0.0);\n"
+ " v_texCoord1 = a_texCoord1;\n"
"#endif\n";
if (lit) {
src += " v_worldPos = world.xy;\n";
diff --git a/tools/tests/canonical-second-uv.test.ts b/tools/tests/canonical-second-uv.test.ts
new file mode 100644
index 000000000..c67da8657
--- /dev/null
+++ b/tools/tests/canonical-second-uv.test.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The engine's canonical vertex stage hands a material the mesh's own second uv set (`v_texCoord1`) wherever the vertices carry one, which the
+ * engine says as MESH_LIGHTMAP: a material that reads a second set (a mask, a dissolve map) is not a bake and has no other way to it.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+// @ts-expect-error — a repo tool, shipped as .mjs with no declarations
+import { loadTwinModule } from '../gen-shader-twins.mjs';
+
+const FRAGMENT_ONLY = `#pragma shader "SecondUv"
+#pragma version 300 es
+#pragma domain Lit
+#pragma fragment
+precision mediump float;
+in vec4 v_color;
+out vec4 fragColor;
+void main() { fragColor = v_color; }
+#pragma end
+`;
+
+type Cook = { valid: boolean; vertGlsl: string; canonicalVaryings: string };
+let module: { esshader_cookInfo(source: string, features: string): Cook } | null = null;
+beforeAll(async () => {
+ try { module = await loadTwinModule(); } catch { module = null; }
+});
+
+describe('the second uv set of a mesh', () => {
+ it('is a varying of the GLSL vertex stage when the draw carries it, and not otherwise', (ctx) => {
+ if (!module) return ctx.skip();
+ const withUv = module.esshader_cookInfo(FRAGMENT_ONLY, 'MESH_LIGHTMAP,MESH_NORMALS');
+ expect(withUv.valid).toBe(true);
+ expect(withUv.vertGlsl).toContain('out highp vec2 v_texCoord1;');
+ expect(withUv.vertGlsl).toContain('v_texCoord1 = a_texCoord1;');
+ const without = module.esshader_cookInfo(FRAGMENT_ONLY, 'MESH_NORMALS');
+ // the stage keeps its `#ifdef`s, so what differs is whether the feature is defined
+ expect(withUv.vertGlsl).toContain('#define MESH_LIGHTMAP');
+ expect(without.vertGlsl).not.toContain('#define MESH_LIGHTMAP');
+ });
+
+ it('is a member of the WGSL varying interface, so a fragment twin reads it by location', (ctx) => {
+ if (!module) return ctx.skip();
+ const info = module.esshader_cookInfo(FRAGMENT_ONLY, '');
+ expect(info.canonicalVaryings).toContain('@location(9) v_texCoord1 : vec2f');
+ });
+});