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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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/desktopindex bb747d95b..0a2712b0a 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit bb747d95bfbb0183eb484804e50ea730495391ae+Subproject commit 0a2712b0a1dd73b36e657cd2133ad6aaba237065diff --git a/pipeline/src/import/cocos/effectConvert.ts b/pipeline/src/import/cocos/effectConvert.tsindex 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 wstruct 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_TANGENTSin highp vec4 v_worldTangent;#define cocos_tangent v_worldTangent@@ -262,7 +318,7 @@ function emulateVertex(program: string, entry: string): Emulated | { error: strideclared.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: sif (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: sneeded.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: sconst 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: sconst 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.tsindex 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 './moimport { 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<Impoconst 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<ImpodepthTest: 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<Impowrite(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<ImpowriteOut(`${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.tsindex 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.cppindex 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.tsnew file mode 100644index 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');+ });+});