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.

fix: preserve authored UVs through model transforms and scattering

yhh1a93998ce272
diff --git a/pipeline/src/modeling/modelOps.ts b/pipeline/src/modeling/modelOps.ts
index 6487ce8f2..186a237d2 100644
--- a/pipeline/src/modeling/modelOps.ts
+++ b/pipeline/src/modeling/modelOps.ts
@@ -13,6 +13,7 @@ import {
selectEdges, selectFaces, sub,
type Edge, type EdgeSelector, type Face, type FaceSelector, type PolyMesh, type Vec3,
} from './polyMesh';
+import { freezeFaceUv } from './modelUv';
const EPS = 1e-6;
const DEG = Math.PI / 180;
@@ -208,7 +209,8 @@ export function transform(mesh: PolyMesh, p: {
if (p.rotate) q = rotateVector(q, p.rotate);
positions[i] = add(add(q, pivot), p.translate ?? [0, 0, 0]);
}
- return { ...mesh, positions };
+ const faces = mesh.faces.map((f) => f.uv && f.v.some((v) => vertices.has(v)) ? freezeFaceUv(mesh, f) : f);
+ return { ...mesh, positions, faces };
}
/** A copy of the chosen faces with vertices of their own, each position put through @p move. */
@@ -217,7 +219,7 @@ function cloneFaces(mesh: PolyMesh, faces: readonly number[], move: (p: Vec3) =>
const positions: Vec3[] = [];
const base = mesh.positions.length;
const out = faces.map((f) => {
- const face = mesh.faces[f]!;
+ const face = freezeFaceUv(mesh, mesh.faces[f]!);
const v = face.v.map((i) => {
let to = remap.get(i);
if (to === undefined) {
@@ -227,7 +229,8 @@ function cloneFaces(mesh: PolyMesh, faces: readonly number[], move: (p: Vec3) =>
}
return to;
});
- return { ...face, v: flip ? v.reverse() : v };
+ return { ...face, v: flip ? v.reverse() : v,
+ ...(flip && face.cornerUvs ? { cornerUvs: [...face.cornerUvs].reverse() } : {}) };
});
return { positions, faces: out };
}
diff --git a/pipeline/src/modeling/modelUv.ts b/pipeline/src/modeling/modelUv.ts
index 9e9410e14..d0199001e 100644
--- a/pipeline/src/modeling/modelUv.ts
+++ b/pipeline/src/modeling/modelUv.ts
@@ -47,7 +47,14 @@ export function uvStep(mesh: PolyMesh, p: UvParams): PolyMesh {
rotate: p.rotate ?? 0,
};
const set = new Set(hit);
- return { ...mesh, faces: mesh.faces.map((f, i) => (set.has(i) ? { ...f, uv } : f)) };
+ return { ...mesh, faces: mesh.faces.map((f, i) => (set.has(i) ? { ...f, uv, cornerUvs: undefined } : f)) };
+}
+
+/** Explicit mappings belong to the surface; resolve them before moving its vertices. Implicit box tiling stays procedural. */
+export function freezeFaceUv(mesh: PolyMesh, face: Face): Face {
+ if (!face.uv || face.cornerUvs) return face;
+ const mapped = faceUvs(mesh, face, 1);
+ return { ...face, cornerUvs: face.v.map((v) => mapped.get(v)!) };
}
/** The in-plane axes a texture is laid along when seen from @p n, with up staying up where it can. */
diff --git a/pipeline/src/modeling/scatter.ts b/pipeline/src/modeling/scatter.ts
index bb9841e7b..73924924c 100644
--- a/pipeline/src/modeling/scatter.ts
+++ b/pipeline/src/modeling/scatter.ts
@@ -8,6 +8,7 @@
*/
import { hash3 } from './hash';
import { triangulateFace } from './triangulate';
+import { freezeFaceUv } from './modelUv';
import { add, boundsOf, compact, cross, dot, faceNormal, length, normalize, scale, selectFaces, sub, type Face, type FaceSelector, type PolyMesh, type Vec3 } from './polyMesh';
export interface ScatterParams {
@@ -107,7 +108,7 @@ export function scatter(mesh: PolyMesh, p: ScatterParams): PolyMesh {
if (taken.length === 0) throw new Error(`\`source\` ${JSON.stringify(p.source)} matched no face`);
const seed = p.seed ?? 1;
const isTaken = new Set(taken);
- const shape = taken.map((f) => mesh.faces[f]!);
+ const shape = taken.map((f) => freezeFaceUv(mesh, mesh.faces[f]!));
const { min, max } = boundsOf(mesh, shape.flatMap((f) => [...f.v]));
const foot: Vec3 = [(min[0] + max[0]) / 2, min[1], (min[2] + max[2]) / 2];
diff --git a/pipeline/tests/modeling-uv-transforms.test.ts b/pipeline/tests/modeling-uv-transforms.test.ts
new file mode 100644
index 000000000..fc13b6f57
--- /dev/null
+++ b/pipeline/tests/modeling-uv-transforms.test.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { MeshChannel } from 'esengine';
+import { bakeModel, type ModelStep } from '../src/modeling';
+
+const leaf: ModelStep[] = [
+ { op: 'plane', size: [20, 40], tag: 'leaf' },
+ { op: 'uv', mode: 'planar', axis: '+y', scale: [20, 40], offset: [0.5, 0.5] },
+];
+function vertices(steps: ModelStep[]) {
+ const { data } = bakeModel({ version: 1, steps });
+ const at = (semantic: number) => data.channels.find((c) => c.semantic === semantic)!.offset;
+ const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
+ return Array.from({ length: data.vertexCount }, (_, i) => ({
+ p: [0, 1, 2].map((k) => view.getFloat32(i * data.vertexStride + at(MeshChannel.Position) + k * 4, true)),
+ uv: [0, 1].map((k) => view.getFloat32(i * data.vertexStride + at(MeshChannel.TexCoord0) + k * 4, true)),
+ }));
+}
+function fullTexture(v: ReturnType<typeof vertices>) {
+ for (const axis of [0, 1]) {
+ expect(Math.min(...v.map((p) => p.uv[axis]!))).toBeCloseTo(0, 5);
+ expect(Math.max(...v.map((p) => p.uv[axis]!))).toBeCloseTo(1, 5);
+ }
+}
+describe('authored UVs travel with leaves and other model parts', () => {
+ it('keeps both texture axes after a translated, rotated and scaled leaf', () => {
+ const v = vertices([...leaf, { op: 'transform', translate: [80, 200, 30], rotate: [90, 0, 0], scale: 2 }]);
+ fullTexture(v);
+ for (const c of v) {
+ expect(c.uv[0]).toBeCloseTo((c.p[0]! - 80) / 40 + 0.5, 5);
+ expect(c.uv[1]).toBeCloseTo((c.p[1]! - 200) / 80 + 0.5, 5);
+ }
+ });
+ it('keeps the full texture on every rotated array and scattered copy', () => {
+ fullTexture(vertices([...leaf, { op: 'array', count: 4, offset: [50, 20, 0], rotate: [30, 45, 0] }]));
+ fullTexture(vertices([...leaf, { op: 'scatter', source: 'leaf', count: 12, within: [[50, 100, 50], [200, 300, 200]], scale: [0.6, 1.8], spin: 360, tilt: 50, seed: 5 }]));
+ });
+ it('mirrors geometry and texture together, including already frozen UVs', () => {
+ const v = vertices([...leaf, { op: 'transform', translate: [30, 0, 0] }, { op: 'mirror', axis: 'x', at: 0, keep: false }]);
+ fullTexture(v);
+ for (const c of v) expect(c.uv[0]).toBeCloseTo((-c.p[0]! - 30) / 20 + 0.5, 5);
+ });
+ it('allows a later UV step to replace coordinates frozen by a transform', () => {
+ const v = vertices([...leaf, { op: 'transform', rotate: [90, 0, 0] },
+ { op: 'uv', mode: 'planar', axis: '+z', scale: [10, 20], offset: [0.5, 0.5] }]);
+ for (const axis of [0, 1]) {
+ expect(Math.min(...v.map((p) => p.uv[axis]!))).toBeCloseTo(-0.5, 5);
+ expect(Math.max(...v.map((p) => p.uv[axis]!))).toBeCloseTo(1.5, 5);
+ }
+ });
+});