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(modeling): a hair step grows cards from a scalp, and a material can cut holes or let light through
yhhebb640efe899
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 64432ff1d..2780187db 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,10 @@ published separately; it ships inside the editor.- **Glyphs can be put on the atlas before they are shown.** The first page of a novel is hundreds of new characters, all landing in one frame. `preloadGlyphs(app, label, text, { budgetMs })` makes them ahead of time, a slice a frame, drawn as that `Text` will draw them, and returns `progress`, `done` and `release()`. On a Snapdragon 8 Elite a book's 2992 characters at 28 px took 145 ms over 25 frames with the worst frame at 9.5 ms, after which the first page's frame went from 49 to 11 ms and no page made a new glyph. Preloaded glyphs hold their atlas pages (4 MB each, a few hundred characters at that size) until `release()`.- **Voxel GI lights what the camera does not see, and bounces light more than once.** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. A ray now brings what it meets at full strength however far it went (it used to fade with distance, 40% at 4 m with 12 cm voxels). Each voxel is weighed by how much of it a surface covers, so a bright patch no longer lights like the whole voxel around it. Together these keep the result close to a path tracer's whatever the voxel size. In a sunlit test room the whole frame carries 0.95 of Cycles' light at the default size and 0.74 at 12 cm voxels; before, it was 0.54 at the default and darker the finer the grid. With the lit patch behind the camera, the walls went from no bounce light to 25–57%. A closed room the sun only lights from outside stays dark. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback does the same in its own passes: each voxel asks the sun's map whether a sunlit surface stands in it, and traces two rays through last frame's grid for the light it is given. In the test room it carries 1.00 of Cycles' light at the default size (it was 0.56) and 0.80 at 12 cm; with the lit patch behind the camera 0.20 (it was 0). Its voxel pass costs about 1.3 ms more at 720p on a desktop.+- **An AI building a model can make hair.** A `hair` step grows cards from a scalp, falling around the head, and writes the strand textures and a Hair material. `hairSway` gives them bones that swing as the game runs, and worn under a head joint they follow the character.++- **An AI building a model can make things see-through.** `material.alpha` is `cutout` for leaves and lace or `blend` for glass and gauze, and a `stain` can set alpha by a pattern or a shape, which a bake keeps on a thin mesh.+- **An AI building a model can shade its creases.** `normalBake` with `occlusion: true` works out how much sky each place on the dense surface sees and writes that as an occlusion map, so cracks, folds and the contact between parts read as depth under ambient light.- **An AI building a model can say what it is made of.** `material` sets roughness and metal for a whole model, `paint` and `stain` for parts of it, and `normalBake` with `surface: true` keeps the differences as a map: wet moss on dry stone, bare steel where paint wore off.diff --git a/desktop b/desktopindex 4e7ae93ca..ec74562aa 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 4e7ae93cad1d54db56c4840d43e93190d78dacbd+Subproject commit ec74562aaef66e3b8cf363a993510a041875d6ecdiff --git a/pipeline/src/modeling/hair.ts b/pipeline/src/modeling/hair.tsnew file mode 100644index 000000000..913ab5c92--- /dev/null+++ b/pipeline/src/modeling/hair.ts@@ -0,0 +1,332 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file hair.ts — the `hair` step: cards growing out of a scalp, what they are cut from, and the bones that swing them.+ *+ * A card is a ribbon of quads from a root on the surface, falling under its own weight and turned+ * aside by the head it would go through. What looks like strands is a texture: alpha cuts each card into+ * them, and the Hair shader lights them along the way they run. The cards take the place of the surface+ * they grew from once the steps are done, because a mesh has one material: a head and its hair are two+ * models. Until then the head stays, so that layer after layer can grow from it and fall around it.+ */+import { TriangleTree, trianglesOf } from './triangleTree';+import { triangulateFace } from './triangulate';+import { hash3 } from './organic';+import { add, boundsOf, compact, cross, dot, faceNormal, normalize, scale, selectFaces, sub, type Face, type FaceSelector, type PolyMesh, type Vec3 } from './polyMesh';+import type { RigJoint, SkinWeights } from './rig';++export interface HairParams {+ /** The scalp: where cards grow from. */+ faces: FaceSelector;+ /** How many. Default 300. */+ count?: number;+ /** How long a card is, in model units. */+ length: number;+ /** How wide at the root, in model units. Default a tenth of its length. */+ width?: number;+ /** Quads along a card: more follows a curve better. Default 6. */+ segments?: number;+ /** How much it falls, 0..1. 0 stands straight out, 1 drops at once. Default 0.7. */+ droop?: number;+ /** A way all of it is combed, added to where it grows. */+ comb?: Vec3;+ /** How unruly, 0..1: how far each card strays from its neighbours. Default 0.15. */+ spread?: number;+ /** How much shorter a card can be than `length`, 0..1. Default 0.3. */+ uneven?: number;+ /** How far a card waves from side to side, in model units. Default 0. */+ wave?: number;+ /** How much narrower its tip is than its root, 0..1. Default 0.6. */+ taper?: number;+ seed?: number;+ color?: readonly number[];+ /** The colour at the tip. Default `color`. */+ tipColor?: readonly number[];+ tag?: string;+}++/** Four strips in the strand texture, so that neighbouring cards are cut differently. */+const STRIPS = 4;+const unit = (a: number, b: number, c: number, seed: number): number => hash3(a, b, c, seed) * 0.5 + 0.5;+const MAX_CARDS = 20000;+const MAX_SEGMENTS = 24;++export function hair(mesh: PolyMesh, p: HairParams): PolyMesh {+ const count = p.count ?? 300;+ const segments = p.segments ?? 6;+ if (!(p.length > 0)) throw new Error(`length ${p.length} must be positive`);+ if (!Number.isInteger(count) || count < 1 || count > MAX_CARDS) throw new Error(`count ${count} must be 1..${MAX_CARDS}`);+ if (!Number.isInteger(segments) || segments < 1 || segments > MAX_SEGMENTS) throw new Error(`segments ${segments} must be 1..${MAX_SEGMENTS}`);+ for (const [name, v] of [['droop', p.droop], ['spread', p.spread], ['uneven', p.uneven], ['taper', p.taper]] as const) {+ if (v !== undefined && !(v >= 0 && v <= 1)) throw new Error(`${name} ${v} must be 0..1`);+ }+ if (p.width !== undefined && !(p.width > 0)) throw new Error(`width ${p.width} must be positive`);+ const hit = selectFaces(mesh, p.faces).filter((f) => mesh.faces[f]!.card === undefined);+ if (hit.length === 0) throw new Error(`\`faces\` ${JSON.stringify(p.faces)} matched no face`);++ const seed = p.seed ?? 1;+ const droop = p.droop ?? 0.7, spread = p.spread ?? 0.15, uneven = p.uneven ?? 0.3, taper = p.taper ?? 0.6;+ const width = p.width ?? p.length * 0.1;+ const comb: Vec3 = p.comb ?? [0, 0, 0];+ const color = p.color ?? [0.25, 0.14, 0.07];+ const tip = p.tipColor ?? color;+ const tag = p.tag ?? 'hair';+ const surface = compact({ positions: mesh.positions, faces: mesh.faces.filter((f) => f.card === undefined) });+ const { min, max } = boundsOf(surface);+ const middle: Vec3 = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];+ // The head and not the layers before: cards lie over each other, and hair does not push hair away.+ const tree = new TriangleTree(trianglesOf(surface));+ const firstCard = mesh.faces.reduce((next, f) => Math.max(next, (f.card ?? -1) + 1), 0);++ // Roots spread by area, so a large face does not go bald beside a small one.+ const pieces: { a: Vec3; b: Vec3; c: Vec3; n: Vec3; area: number }[] = [];+ for (const f of hit) {+ const face = mesh.faces[f]!;+ const n = faceNormal(mesh, face);+ for (const [a, b, c] of triangulateFace(mesh, face)) {+ const [pa, pb, pc] = [mesh.positions[a]!, mesh.positions[b]!, mesh.positions[c]!];+ pieces.push({ a: pa, b: pb, c: pc, n, area: Math.hypot(...cross(sub(pb, pa), sub(pc, pa))) / 2 });+ }+ }+ const running: number[] = [];+ let total = 0;+ for (const piece of pieces) { total += piece.area; running.push(total); }+ if (!(total > 0)) throw new Error('`faces` have no area to grow from');++ const positions: Vec3[] = [...mesh.positions];+ const faces: Face[] = [...mesh.faces];+ for (let index = 0; index < count; index++) {+ const card = firstCard + index;+ const r = (i: number): number => unit(index, i, 11, seed);+ let lo = 0, hi = pieces.length - 1;+ const pick = r(0) * total;+ while (lo < hi) { const m = (lo + hi) >> 1; if (running[m]! < pick) lo = m + 1; else hi = m; }+ const piece = pieces[lo]!;+ let [u, v] = [r(1), r(2)];+ if (u + v > 1) { u = 1 - u; v = 1 - v; }+ const root = add(add(scale(piece.a, 1 - u - v), scale(piece.b, u)), scale(piece.c, v));+ const out = piece.n;+ const stray: Vec3 = [(r(3) - 0.5) * 2 * spread, (r(4) - 0.5) * 2 * spread, (r(5) - 0.5) * 2 * spread];+ const size = p.length * (1 - uneven * r(6));+ const step = size / segments;+ // Each step leans further toward the ground, by as much as `droop` asks over the card's whole length.+ const pull = droop * 2.4 / segments;+ let d = normalize(add(add(out, comb), stray));+ let at = add(root, scale(out, step * 0.05));+ // The way across the card stays square to it, and its face stays toward the outside.+ const yaw = (r(7) - 0.5) * spread * 2;+ const start = positions.length;+ const strip = Math.floor(r(8) * STRIPS);+ const phase = r(9) * Math.PI * 2;+ const rows: { at: Vec3; side: Vec3 }[] = [];+ for (let s = 0; s <= segments; s++) {+ const away = normalize(sub(at, middle));+ let across = cross(d, add(scale(out, 0.5), scale(away, 0.5)));+ if (dot(across, across) < 1e-8) across = cross(d, [0.3, 0.2, 0.9]);+ across = normalize(add(normalize(across), scale(d, yaw)));+ const t = s / segments;+ const sway = p.wave ? scale(across, Math.sin(t * 7 + phase) * p.wave * t) : [0, 0, 0] as Vec3;+ rows.push({ at: add(at, sway), side: scale(across, (width * (1 - taper * t)) / 2) });+ if (s === segments) break;+ d = normalize(add(scale(d, 1 - pull), add(scale([0, -1, 0], pull), scale(comb, pull * 0.5))));+ // Turned aside rather than through: it slides over what it grows from.+ for (let tries = 0; tries < 6 && tree.blocked(at[0], at[1], at[2], d[0], d[1], d[2], step * 1.2); tries++) {+ d = normalize(add(d, scale(normalize(add(out, normalize(sub(at, middle)))), 0.5)));+ }+ at = add(at, scale(d, step));+ }+ rows.forEach((row, s) => {+ const v0 = 1 - s / segments;+ positions.push(sub(row.at, row.side), add(row.at, row.side));+ if (s === 0) return;+ const [l0, r0, l1, r1] = [start + (s - 1) * 2, start + (s - 1) * 2 + 1, start + s * 2, start + s * 2 + 1];+ const v1 = 1 - (s - 1) / segments;+ const [u0, u1] = [(strip + 0.02) / STRIPS, (strip + 0.98) / STRIPS];+ const t = (s - 0.5) / segments;+ const paint = [0, 1, 2].map((k) => color[k]! + (tip[k]! - color[k]!) * t);+ faces.push({+ v: [l0, l1, r1, r0], tag, smooth: true, card,+ color: [paint[0]!, paint[1]!, paint[2]!, 1] as const,+ cornerUvs: [[u0, v1], [u0, v0], [u1, v0], [u1, v1]],+ });+ });+ }+ return compact({ positions, faces });+}++/** Cards the mesh has, or nothing: hair has a material of its own. */+export const hasCards = (mesh: PolyMesh): boolean => mesh.faces.some((f) => f.card !== undefined);++/** Just the cards, once nothing more will grow from what they grew from. */+export const cardsOnly = (mesh: PolyMesh): PolyMesh => compact({ positions: mesh.positions, faces: mesh.faces.filter((f) => f.card !== undefined) });++export interface HairSway {+ /** Bone chains the cards are shared out among. Default 12. */+ chains?: number;+ /** Bones to a chain. Default 3. */+ bones?: number;+ /** How hard it goes back to where it was, 0..1. Default 0.08. */+ stiffness?: number;+ /** How much speed it loses each frame, 0..1. Default 0.3. */+ drag?: number;+ /** A ball it stays out of, in model units: the head. */+ collider?: { at: Vec3; radius: number };+}++/**+ * Chains down through the cards, and each card bound to its nearest. Not the weights a body is given, which are found+ * across a connected surface: a card is its own small surface, and only the way along it matters.+ */+export function hairRig(mesh: PolyMesh, sway: HairSway): { joints: RigJoint[]; skin: SkinWeights; chainRoots: number[] } {+ const cards = new Map<number, Face[]>();+ for (const face of mesh.faces) {+ if (face.card === undefined) continue;+ const at = cards.get(face.card);+ if (at) at.push(face); else cards.set(face.card, [face]);+ }+ const ids = [...cards.keys()];+ const chainCount = Math.min(sway.chains ?? 12, ids.length);+ const bones = sway.bones ?? 3;+ /** Where a card is, a share of the way along. */+ const along = (faces: Face[], t: number): Vec3 => {+ const i = Math.min(faces.length - 1, Math.floor(t * faces.length));+ const face = faces[i]!;+ const within = t * faces.length - i;+ const [l0, l1, r1, r0] = face.v as [number, number, number, number];+ const near = scale(add(mesh.positions[l0]!, mesh.positions[r0]!), 0.5);+ const far = scale(add(mesh.positions[l1]!, mesh.positions[r1]!), 0.5);+ return add(scale(near, 1 - within), scale(far, within));+ };+ const roots = ids.map((id) => along(cards.get(id)!, 0));++ // Centres spread as far apart as they will go, then settled: the same answer every time, as a random start would not give.+ const centres: Vec3[] = [roots[0]!];+ while (centres.length < chainCount) {+ let far = 0, best = -1;+ roots.forEach((q, i) => {+ const d = Math.min(...centres.map((c) => dot(sub(q, c), sub(q, c))));+ if (d > best) { best = d; far = i; }+ });+ centres.push(roots[far]!);+ }+ const owner = new Int32Array(ids.length);+ for (let pass = 0; pass < 6; pass++) {+ roots.forEach((q, i) => {+ let best = Infinity;+ centres.forEach((c, k) => { const d = dot(sub(q, c), sub(q, c)); if (d < best) { best = d; owner[i] = k; } });+ });+ centres.forEach((_, k) => {+ let sum: Vec3 = [0, 0, 0], n = 0;+ roots.forEach((q, i) => { if (owner[i] === k) { sum = add(sum, q); n++; } });+ if (n) centres[k] = scale(sum, 1 / n);+ });+ }++ const joints: RigJoint[] = [];+ let middle: Vec3 = [0, 0, 0];+ for (const q of roots) middle = add(middle, q);+ joints.push({ name: 'hair', at: scale(middle, 1 / roots.length), parent: -1, children: [] });+ const chainRoots: number[] = [];+ const firstBone: number[] = [];+ for (let k = 0; k < chainCount; k++) {+ const mine = ids.filter((_, i) => owner[i] === k);+ let parent = 0;+ firstBone.push(joints.length);+ chainRoots.push(joints.length);+ for (let b = 0; b <= bones; b++) {+ let sum: Vec3 = [0, 0, 0];+ for (const id of mine) sum = add(sum, along(cards.get(id)!, b / bones));+ const index = joints.length;+ joints.push({ name: `hair${k}.${b}`, at: mine.length ? scale(sum, 1 / mine.length) : centres[k]!, parent, children: [] });+ joints[parent]!.children.push(index);+ parent = index;+ }+ }++ const count = mesh.positions.length;+ const skin: SkinWeights = { joints: new Uint16Array(count * 4), weights: new Float32Array(count * 4), dominant: joints.map(() => 0) };+ const ownerOf = new Map(ids.map((id, i) => [id, owner[i]!]));+ for (const [id, faces] of cards) {+ const first = firstBone[ownerOf.get(id)!]!;+ faces.forEach((face, f) => {+ const [l0, l1, r1, r0] = face.v as [number, number, number, number];+ const put = (vertex: number, t: number): void => {+ const place = Math.min(bones - 1e-6, t * bones);+ const b = Math.floor(place);+ const w = place - b;+ skin.joints[vertex * 4] = first + b;+ skin.joints[vertex * 4 + 1] = first + b + 1;+ skin.weights[vertex * 4] = 1 - w;+ skin.weights[vertex * 4 + 1] = w;+ skin.dominant[w < 0.5 ? first + b : first + b + 1]!++;+ };+ put(l0, f / faces.length); put(r0, f / faces.length);+ put(l1, (f + 1) / faces.length); put(r1, (f + 1) / faces.length);+ });+ }+ return { joints, skin, chainRoots };+}++export interface HairMaps {+ /** What the cards are cut from: tone in colour, strands in alpha. Multiplies the cards' colour. */+ strands: { size: number; rgba: Uint8Array };+ /** Which way the strands run: all along v. */+ flow: { size: number; rgba: Uint8Array };+ /** Where each strand's highlight shifts along it. */+ shift: { size: number; rgba: Uint8Array };+}++const STRANDS_A_STRIP = 34;++/** The textures a card reads. Numbers, not pictures, so they are stored and read without sRGB. */+export function hairMaps(seed = 1, size = 512): HairMaps {+ const coverage = new Float32Array(size * size);+ const tone = new Float32Array(size * size).fill(0.75);+ const stripWide = size / STRIPS;+ for (let strip = 0; strip < STRIPS; strip++) {+ // Keeps clear of the strip's edges, so that nothing bleeds in from the next.+ const lo = strip * stripWide + 2, hi = (strip + 1) * stripWide - 2;+ for (let n = 0; n < STRANDS_A_STRIP; n++) {+ const r = (i: number): number => unit(strip, n, i, seed);+ // Thick in the middle of a card and thin to its edges, as a lock is.+ const offset = (r(0) + r(1) + r(2)) / 3;+ const x0 = lo + (hi - lo) * offset;+ const lean = (r(3) - 0.5) * stripWide * 0.25;+ const halfWidth = (0.9 + r(4) * 1.6) * (size / 512);+ // Short of the card's end: what is left of a strand there is thinner than a pixel, and breaks up into specks.+ const reach = 0.55 + r(5) * 0.37;+ const shade = 0.55 + r(6) * 0.45;+ for (let y = 0; y < size; y++) {+ const t = (y + 0.5) / size;+ if (t > reach) break;+ const left = t / reach;+ const middle = x0 + lean * t + Math.sin(t * 6 + r(7) * 6) * stripWide * 0.015;+ const w = halfWidth * (1 - 0.5 * left * left);+ const from = Math.max(Math.ceil(lo), Math.floor(middle - w - 1));+ const to = Math.min(Math.floor(hi), Math.ceil(middle + w + 1));+ for (let x = from; x <= to; x++) {+ const a = Math.max(0, Math.min(1, w + 0.5 - Math.abs(x + 0.5 - middle))) * Math.min(1, (1 - left) * 10);+ const at = y * size + x;+ if (a > coverage[at]!) { coverage[at] = a; tone[at] = shade; }+ }+ }+ }+ }+ const strands = new Uint8Array(size * size * 4);+ for (let i = 0; i < size * size; i++) {+ const v = Math.round(tone[i]! * 255);+ strands[i * 4] = v; strands[i * 4 + 1] = v; strands[i * 4 + 2] = v;+ strands[i * 4 + 3] = Math.round(coverage[i]! * 255);+ }+ const flow = new Uint8Array(4 * 4 * 4);+ for (let i = 0; i < 16; i++) flow.set([128, 255, 128, 255], i * 4);+ const shiftSize = 128;+ const shift = new Uint8Array(shiftSize * shiftSize * 4);+ for (let y = 0; y < shiftSize; y++) {+ for (let x = 0; x < shiftSize; x++) {+ const v = Math.round(unit(x, Math.floor(y / 16), 3, seed) * 255);+ shift.set([v, v, v, 255], (y * shiftSize + x) * 4);+ }+ }+ return { strands: { size, rgba: strands }, flow: { size: 4, rgba: flow }, shift: { size: shiftSize, rgba: shift } };+}diff --git a/pipeline/src/modeling/index.ts b/pipeline/src/modeling/index.tsindex e88dba593..2b0024387 100644--- a/pipeline/src/modeling/index.ts+++ b/pipeline/src/modeling/index.ts@@ -10,7 +10,7 @@ export {} from './modelSource';export { organic, ORGANIC_DEFAULT_RESOLUTION, ORGANIC_MAX_RESOLUTION, type OrganicParams, type OrganicPart } from './organic';export { needsPreparing, prepareModeling } from './booleans';-export { bakeModel, modelMaterialDoc, type BakedModel, type ModelReport } from './modelBake';+export { bakeModel, HAIR_CUTOFF, modelMaterialDoc, type BakedModel, type ModelReport } from './modelBake';export { bakeNormalMap, type NormalBakeReport, type NormalMap } from './normalBake';export type { FaceSelector } from './polyMesh';export { DEFAULT_MODEL_VIEWS, MODEL_VIEWS, renderModelSheet, renderRigSheet, type ModelSheet, type ModelViewName, type RigViewOptions } from './modelViews';diff --git a/pipeline/src/modeling/modelBake.ts b/pipeline/src/modeling/modelBake.tsindex c60300693..c2bb2296e 100644--- a/pipeline/src/modeling/modelBake.ts+++ b/pipeline/src/modeling/modelBake.ts@@ -10,6 +10,7 @@*/import { BlendMode, CullMode, MATERIAL_FORMAT_VERSION, MeshChannel, MeshChannelType, packChannels, unwrapLightmapUV, type MeshData, type MeshMorphTargets } from 'esengine';import { generateTangents } from '../assets/meshTangents';+import { hairMaps, hairRig, hasCards, type HairMaps } from './hair';import { triangulateFace } from './triangulate';import { faceUvs } from './modelUv';import { adjustWeights, bindMatrices, computeWeights, resolveJoints, shapeDeltas, type ControllerIk, type RigGoal, type RigJoint, type SkinWeights } from './rig';@@ -23,6 +24,7 @@ import {const DEFAULT_SMOOTH_ANGLE = 30;const DEFAULT_NORMAL_SIZE = 1024;const HEAVY_TRIANGLES = 300000;+export const HAIR_CUTOFF = 0.35;const LIGHTMAP_TRIANGLES = 150000;export interface ModelReport {@@ -59,6 +61,8 @@ export interface BakedModel {report: ModelReport;/** Present on a rigged model. */rig?: { joints: RigJoint[]; skin: SkinWeights; ik?: readonly ControllerIk[]; goals?: readonly RigGoal[] };+ /** Present on a model of hair cards: the textures they read, and where its chains start if it swings. */+ hair?: { maps: HairMaps; chainRoots?: number[] };/** Present where a source has shapes: three offsets per surface vertex, for each. */shapes?: { names: string[]; deltas: Float32Array[] };/** One triangle per entry: its three positions' indices, and the face it came from. */@@ -272,18 +276,41 @@ function withTangents(mesh: MeshData): MeshData {}/** What a material has to say about a model, or null where a plain MeshRenderer says all of it. */-export function modelMaterialDoc(source: ModelSource, cullBackfaces: boolean, maps: { normal?: string | null; surface?: string | null; occlusion?: string | null }): Record<string, unknown> | null {+export function modelMaterialDoc(source: ModelSource, cullBackfaces: boolean, maps: { normal?: string | null; surface?: string | null; occlusion?: string | null; hair?: { flow: string; shift: string } | null }): Record<string, unknown> | null {const { material } = source;+ if (maps.hair) {+ return {+ version: MATERIAL_FORMAT_VERSION,+ type: 'material',+ // Cut out and feathered by coverage, which only an unblended draw gets; both sides of a card show.+ shader: 'builtin:hair',+ blendMode: BlendMode.None,+ depthTest: true,+ depthWrite: true,+ cull: CullMode.None,+ properties: {+ u_flowMap: maps.hair.flow, u_shiftMap: maps.hair.shift,+ u_alphaCutoff: HAIR_CUTOFF, u_tipSoftness: 0.2,+ u_roughness: material?.roughness ?? 0.4, u_specular: 0.7, u_lobeGain: 0.5,+ u_shiftAmount: 0.35, u_translucency: 0.2, u_strandDiffuse: 0.45, u_rootDark: 0,+ u_clumpCount: 5, u_clumpTone: 0.25, u_clumpShift: 0.4, u_clumpGap: 0.4,+ u_hairShadow: 400,+ },+ };+ }if (!material && !maps.surface && !maps.occlusion) return null;+ const blended = material?.alpha === 'blend';return {version: MATERIAL_FORMAT_VERSION,type: 'material',shader: 'builtin:model',- blendMode: BlendMode.None,+ blendMode: blended ? BlendMode.Normal : BlendMode.None,depthTest: true,- depthWrite: true,- cull: cullBackfaces ? CullMode.Back : CullMode.None,+ // What is seen through a blended surface is drawn first, so it must not stop what lies behind it from being drawn.+ depthWrite: !blended,+ cull: cullBackfaces && !material?.alpha ? CullMode.Back : CullMode.None,properties: {+ ...(material?.alpha === 'cutout' ? { u_alphaCutoff: material.cutoff ?? 0.5 } : {}),...(maps.normal ? { u_normalMap: maps.normal } : {}),...(maps.occlusion ? {u_occlusionMap: maps.occlusion,@@ -309,6 +336,9 @@ export function bakeModel(raw: unknown): BakedModel {const joints = resolveJoints(source.rig);rig = { joints, skin: adjustWeights(mesh, joints, computeWeights(mesh, joints), source.rig.adjust ?? []), ik: source.controller?.ik ?? [], goals: source.rig.goals ?? [] };}+ const cards = hasCards(mesh);+ const swing = cards && source.hairSway ? hairRig(mesh, source.hairSway) : null;+ if (swing) rig = { joints: swing.joints, skin: swing.skin, ik: [], goals: [] };const shapes = source.shapes ? { names: source.shapes.map((s) => s.name), deltas: source.shapes.map((s) => shapeDeltas(mesh, s)) } : undefined;const bake = source.normalBake;const size = bake?.size ?? DEFAULT_NORMAL_SIZE;@@ -324,6 +354,9 @@ export function bakeModel(raw: unknown): BakedModel {throw new Error(`${triangleCount} triangles break into too many pieces to lay out in one texture: decimate further, or give the surface less to carve before it`);}copyLightmapUvToBase(unwrapped);+ } else if (cards) {+ // Cards are read from a strand texture by the frame it runs in, and nobody bakes light onto hair.+ unwrapped = withTangents(baked);} else if (!rig && !shapes) {// This is optional, and costs minutes past a point where nobody would bake light onto the model anyway. Nothing else needs it.layoutNote = 'it has no lightmap UV: baked light will not land on it, and is not worth it at this density';@@ -368,14 +401,14 @@ export function bakeModel(raw: unknown): BakedModel {warnings.push(`faces say their own roughness or metallic, and nothing carries that: give normalBake \`surface: true\`${uniform ? ', or say it once in `material`' : ''}`);}if (triangleCount > HEAVY_TRIANGLES) warnings.push(`${triangleCount} triangles is a lot to draw: end with a \`decimate\`, and \`normalBake\` to keep the detail`);- if (openEdges) warnings.push(`${openEdges} open edge${openEdges > 1 ? 's' : ''}: the surface has holes you can see into`);+ if (openEdges && !cards) warnings.push(`${openEdges} open edge${openEdges > 1 ? 's' : ''}: the surface has holes you can see into`);if (nonManifoldEdges) warnings.push(`${nonManifoldEdges} edge${nonManifoldEdges > 1 ? 's' : ''} shared by more than two faces, which a later bevel refuses: \`weld\` may have joined things that should stay apart, or on an organic skin two parts just touch, so overlap them or raise blend`);if (flippedEdges) warnings.push(`${flippedEdges} edge${flippedEdges > 1 ? 's' : ''} between faces wound opposite ways: part of the surface faces inward`);if (degenerateFaces) warnings.push(`${degenerateFaces} face${degenerateFaces > 1 ? 's' : ''} with no area; \`weld\` removes them`);if (insideOutShells) warnings.push(`${insideOutShells} closed shell${insideOutShells > 1 ? 's are' : ' is'} inside out`);const jointReport = rig ? Object.fromEntries(rig.joints.map((j, i) => [j.name, rig!.skin.dominant[i]!])) : undefined;- if (rig) {+ if (rig && !cards) {// A tip often moves nothing: it marks where the last bone ends.const idle = rig.joints.filter((j, i) => j.children.length > 0 && rig!.skin.dominant[i] === 0).map((j) => j.name);if (idle.length) warnings.push(`joint${idle.length > 1 ? 's' : ''} ${idle.join(', ')} move${idle.length > 1 ? '' : 's'} no vertex the most: too near another, or outside the surface`);@@ -399,6 +432,7 @@ export function bakeModel(raw: unknown): BakedModel {data: unwrapped,...(rig ? { rig } : {}),...(shapes ? { shapes } : {}),+ ...(cards ? { hair: { maps: hairMaps((source.steps.find((s) => s.op === 'hair')?.seed as number | undefined) ?? 1), ...(swing ? { chainRoots: swing.chainRoots } : {}) } } : {}),...(bake && high ? { detail: { high, size, ...(bake.distance !== undefined ? { distance: bake.distance } : {}), smoothAngle: source.smoothAngle ?? DEFAULT_SMOOTH_ANGLE, ...(lowColors ? { lowColors } : {}), ...(bake.occlusion ? { occlusion: typeof bake.occlusion === 'object' ? bake.occlusion : {} } : {}), ...(bake.surface ? { surface: { roughness: source.material?.roughness ?? 1, metallic: source.material?.metallic ?? 0 } } : {}) } } : {}),triangles: triangles.flatMap((tris, face) => tris.map((v) => ({ v, face }))),report: {diff --git a/pipeline/src/modeling/modelSource.ts b/pipeline/src/modeling/modelSource.tsindex d8a8d4436..afcc5e4b2 100644--- a/pipeline/src/modeling/modelSource.ts+++ b/pipeline/src/modeling/modelSource.ts@@ -21,6 +21,7 @@ import { subdivide } from './subdivide';import { decimate, triangleCount } from './decimate';import { displace, DISPLACE_PATTERNS } from './displace';import { stain } from './stain';+import { cardsOnly, hair, hasCards, type HairSway } from './hair';import { checkAnimations, checkController, checkRig, checkShapes, type AnimationSource, type ControllerSource, type RigSource, type ShapeSource } from './rig';import { compact, type Face, type FaceSelector, type PolyMesh, type Vec3 } from './polyMesh';@@ -42,6 +43,8 @@ export interface ModelSource {uvScale?: number;/** Lay the base UV out so no two triangles share texels: for a texture painted for this one model, where tiling is not wanted. */uvAtlas?: boolean;+ /** Bones through a hair model's cards, which swing as the game runs. */+ hairSway?: HairSway;/** What every face is made of until a `paint` or `stain` says otherwise. */material?: ModelMaterial;/** Carries a denser state of the steps onto the final surface as a normal map. It lays the base UV out as uvAtlas does. */@@ -62,6 +65,10 @@ export interface ModelMaterial {roughness?: number;/** 0 is anything else, 1 is metal. Default 0. */metallic?: number;+ /** What a colour's alpha means. `cutout` is solid or nothing, by `cutoff`: leaves, lace, torn edges. `blend` lets through what is behind: glass, gauze. Default neither. */+ alpha?: 'cutout' | 'blend';+ /** Below this a `cutout` is a hole. Default 0.5. */+ cutoff?: number;}export interface NormalBakeOcclusion {@@ -124,7 +131,8 @@ export const MODEL_OPS: Record<string, OpSpec> = {boolean: { params: { operation: 'operation', with: 'faces', from: 'faces', keep: 'boolean', tag: 'string', color: 'color' }, required: ['operation', 'with'], run: booleanOp as unknown as OpSpec['run'], says: 'cuts or joins closed solids: subtract `with` from `from` makes a real hole' },subdivide: { params: { faces: 'faces', levels: 'integer', crease: 'number' }, required: [], run: subdivide as unknown as OpSpec['run'], says: 'rounds whole shells into smooth surfaces, keeping edges sharper than `crease` degrees' },displace: { params: { faces: 'faces', near: 'near', pattern: 'pattern', amplitude: 'number', scale: 'number', octaves: 'integer', seed: 'integer', stretch: 'vec3', warp: 'number', width: 'number', axis: 'axis', mirror: 'axis', detail: 'number' }, required: ['pattern', 'amplitude', 'scale'], run: ((mesh: PolyMesh, params: never) => displace(mesh, params)) as OpSpec['run'], says: 'pushes fine detail out of the surface along its normal, splitting faces as far as the pattern needs: bumps, wrinkles, cracks, scales, pores, ribs, weave or scratches' },- stain: { params: { faces: 'faces', near: 'near', hard: 'boolean', color: 'color', roughness: 'number', metallic: 'number', amount: 'number', pattern: 'pattern', scale: 'number', octaves: 'integer', seed: 'integer', stretch: 'vec3', warp: 'number', width: 'number', axis: 'axis', mirror: 'axis', threshold: 'number', softness: 'number', where: 'where', reach: 'number', facing: 'vec3', detail: 'number' }, required: [], run: ((mesh: PolyMesh, params: never) => stain(mesh, params)) as OpSpec['run'], says: 'lays colour, `roughness` or `metallic` over the surface by a pattern, by shape (`where`: cavity for dirt in what is sunken, edges for wear on what stands out), by which way it faces, or around a spot: pupils, moss, grime' },+ hair: { params: { faces: 'faces', count: 'integer', length: 'number', width: 'number', segments: 'integer', droop: 'number', comb: 'vec3', spread: 'number', uneven: 'number', wave: 'number', taper: 'number', seed: 'integer', color: 'color', tipColor: 'color', tag: 'string' }, required: ['faces', 'length'], run: hair as unknown as OpSpec['run'], says: 'grows cards of hair from these faces, falling around what is there; run it again for another layer, and only the cards are kept' },+ stain: { params: { faces: 'faces', near: 'near', hard: 'boolean', color: 'color', roughness: 'number', metallic: 'number', alpha: 'number', amount: 'number', pattern: 'pattern', scale: 'number', octaves: 'integer', seed: 'integer', stretch: 'vec3', warp: 'number', width: 'number', axis: 'axis', mirror: 'axis', threshold: 'number', softness: 'number', where: 'where', reach: 'number', facing: 'vec3', detail: 'number' }, required: [], run: ((mesh: PolyMesh, params: never) => stain(mesh, params)) as OpSpec['run'], says: 'lays colour, `roughness`, `metallic` or `alpha` over the surface by a pattern, by shape (`where`: cavity for dirt in what is sunken, edges for wear on what stands out), by which way it faces, or around a spot: pupils, moss, grime' },decimate: { params: { from: 'string', faces: 'faces', ratio: 'number', triangles: 'integer', error: 'number' }, required: [], run: decimate as unknown as OpSpec['run'], says: 'leaves fewer triangles over the same surface: `ratio` to keep or `triangles` to end with, stopping sooner if the surface would move more than `error` (default 0.02) of its size; `from` thins the surface as it stood after that step, before its fine detail' },uv: { params: { faces: 'faces', mode: 'uvmode', axis: 'string', at: 'vec3', scale: 'number|vec2only', repeat: 'number|vec2only', offset: 'vec2', rotate: 'number' }, required: ['mode'], run: uvStep as unknown as OpSpec['run'], says: 'sets how faces take a texture: box, planar, cylinder or sphere' },delete: { params: { faces: 'faces' }, required: ['faces'], run: ops.deleteFaces as OpSpec['run'], says: 'removes faces, leaving a hole' },@@ -335,8 +343,8 @@ export function validateModelSource(raw: unknown): ModelSource {if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new ModelBuildError('a model source must be an object with `steps`', null, null, null);const source = raw as Record<string, unknown>;for (const key of Object.keys(source)) {- if (!['version', 'smoothAngle', 'uvScale', 'uvAtlas', 'material', 'normalBake', 'rig', 'shapes', 'animations', 'controller', 'steps'].includes(key)) {- throw new ModelBuildError(`unknown field "${key}"; a model source has version, smoothAngle, uvScale, uvAtlas, material, normalBake, rig, shapes, animations, controller, steps`, null, null, null);+ if (!['version', 'smoothAngle', 'uvScale', 'uvAtlas', 'material', 'hairSway', 'normalBake', 'rig', 'shapes', 'animations', 'controller', 'steps'].includes(key)) {+ throw new ModelBuildError(`unknown field "${key}"; a model source has version, smoothAngle, uvScale, uvAtlas, material, hairSway, normalBake, rig, shapes, animations, controller, steps`, null, null, null);}}if (source.version !== undefined && source.version !== MODEL_SOURCE_VERSION) {@@ -372,12 +380,32 @@ export function validateModelSource(raw: unknown): ModelSource {if (!Array.isArray(source.steps)) throw new ModelBuildError('`steps` must be an array', null, null, null);if (source.material !== undefined) {const m = source.material as Record<string, unknown> | null;- if (typeof m !== 'object' || m === null || Array.isArray(m)) throw new ModelBuildError('material must be { roughness?, metallic? }', null, null, null);+ if (typeof m !== 'object' || m === null || Array.isArray(m)) throw new ModelBuildError('material must be { roughness?, metallic?, alpha?, cutoff? }', null, null, null);for (const [key, value] of Object.entries(m)) {- if (key !== 'roughness' && key !== 'metallic') throw new ModelBuildError(`material has an unknown field "${key}"; it takes roughness, metallic`, null, null, null);+ if (key === 'alpha') {+ if (value !== 'cutout' && value !== 'blend') throw new ModelBuildError('material.alpha must be cutout or blend', null, null, null);+ continue;+ }+ if (!['roughness', 'metallic', 'cutoff'].includes(key)) throw new ModelBuildError(`material has an unknown field "${key}"; it takes roughness, metallic, alpha, cutoff`, null, null, null);if (!(isNum(value) && value >= 0 && value <= 1)) throw new ModelBuildError(`material.${key} must be 0..1`, null, null, null);}}+ if (Array.isArray(source.steps) && (source.steps as Partial<ModelStep>[]).some((s) => s?.op === 'hair')) {+ if (source.normalBake !== undefined || source.uvAtlas) throw new ModelBuildError('a hair model\'s cards take their texture where the step puts them, so it has no normalBake or uvAtlas', null, null, null);+ if (source.rig !== undefined || source.shapes !== undefined) throw new ModelBuildError('a hair model has no rig or shapes of its own: `hairSway` gives it bones, and placed under a head joint it follows that', null, null, null);+ }+ if (source.hairSway !== undefined) {+ const sway = source.hairSway as Record<string, unknown> | null;+ const fail = (what: string): never => { throw new ModelBuildError(`hairSway ${what}`, null, null, null); };+ if (typeof sway !== 'object' || sway === null || Array.isArray(sway)) fail('must be { chains?, bones?, stiffness?, drag?, collider? }');+ for (const key of Object.keys(sway!)) if (!['chains', 'bones', 'stiffness', 'drag', 'collider'].includes(key)) fail(`has an unknown field "${key}"; it takes chains, bones, stiffness, drag, collider`);+ const { chains, bones, stiffness, drag, collider } = sway!;+ if (chains !== undefined && !(Number.isInteger(chains) && (chains as number) >= 1 && (chains as number) <= 60)) fail('chains must be 1..60');+ if (bones !== undefined && !(Number.isInteger(bones) && (bones as number) >= 1 && (bones as number) <= 4)) fail('bones must be 1..4');+ for (const [name, v] of [['stiffness', stiffness], ['drag', drag]] as const) if (v !== undefined && !(isNum(v) && v >= 0 && v <= 1)) fail(`${name} must be 0..1`);+ if (collider !== undefined && KIND_CHECK.near(collider)) fail('collider must be { at: [x, y, z], radius }');+ if (!(Array.isArray(source.steps) && (source.steps as Partial<ModelStep>[]).some((s) => s?.op === 'hair'))) fail('needs a hair step to swing');+ }if (source.normalBake !== undefined) {const bad = checkNormalBake(source.normalBake, source.steps as Partial<ModelStep>[]);if (bad) throw new ModelBuildError(`normalBake ${bad}`, null, null, null);@@ -461,7 +489,7 @@ export function buildPolyMesh(source: ModelSource): ModelBuild {if (index === highAfter) high = compact(mesh);if (id && wanted.has(id)) kept.set(id, mesh);});- return { mesh: compact(mesh), steps, notes, ...(high ? { high } : {}) };+ return { mesh: hasCards(mesh) ? cardsOnly(mesh) : compact(mesh), steps, notes, ...(high ? { high } : {}) };}// ---- Edits: changing a source without restating it ------------------------------diff --git a/pipeline/src/modeling/modelUv.ts b/pipeline/src/modeling/modelUv.tsindex 8701a025c..9e9410e14 100644--- a/pipeline/src/modeling/modelUv.ts+++ b/pipeline/src/modeling/modelUv.ts@@ -68,6 +68,10 @@ function finish(uv: FaceUv | undefined, u: number, v: number): [number, number]/** The UV at each corner of @p face. */export function faceUvs(mesh: PolyMesh, face: Face, uvScale: number): Map<number, readonly [number, number]> {const out = new Map<number, readonly [number, number]>();+ if (face.cornerUvs) {+ face.v.forEach((i, n) => out.set(i, face.cornerUvs![n]!));+ return out;+ }const uv = face.uv;if (!uv || uv.mode === 'box' || uv.mode === 'planar') {const normal = uv?.mode === 'planar' ? axisVector(uv.axis as never) : faceNormal(mesh, face);diff --git a/pipeline/src/modeling/normalBake.ts b/pipeline/src/modeling/normalBake.tsindex aba0d31cf..61be393d5 100644--- a/pipeline/src/modeling/normalBake.ts+++ b/pipeline/src/modeling/normalBake.ts@@ -15,6 +15,7 @@*/import { MeshChannel, MeshChannelType, type MeshData } from 'esengine';import { cornerNormals, type BakedModel } from './modelBake';+import { TriangleTree } from './triangleTree';import { triangulateFace } from './triangulate';import { boundsOf, type PolyMesh } from './polyMesh';@@ -22,7 +23,6 @@ import { boundsOf, type PolyMesh } from './polyMesh';const DEFAULT_DISTANCE = 0.05;/** Texels past each chart's edge that take its values: what bilinear reads and the small mips average there. */const GUTTER = 16;-const LEAF = 4;/** Above this share of texels finding no surface, the map is probably missing what it was made for. */const MISSED_WARNING = 0.05;/** Degrees of mean bend past which a map is mostly slopes too steep to shade. */@@ -68,178 +68,6 @@ export interface NormalMap {warnings: string[];}-/** A bounding-volume hierarchy over triangles, in flat arrays: a dense model is several hundred thousand of them. */-class TriangleTree {- private readonly order: Int32Array;- private readonly boxes: Float64Array;- /** Per node: a leaf's first triangle in `order` and its count, or the right child and 0. */- private readonly links: Int32Array;- private nodes = 0;- private readonly stack = new Int32Array(128);-- constructor(private readonly corners: Float64Array) {- const count = corners.length / 9;- this.order = Int32Array.from({ length: count }, (_, i) => i);- this.boxes = new Float64Array(count * 2 * 6 + 6);- this.links = new Int32Array(count * 2 * 2 + 2);- const centers = new Float64Array(count * 3);- for (let t = 0; t < count; t++) {- for (let k = 0; k < 3; k++) centers[t * 3 + k] = (corners[t * 9 + k]! + corners[t * 9 + 3 + k]! + corners[t * 9 + 6 + k]!) / 3;- }- this.build(0, count, centers);- }-- private build(first: number, count: number, centers: Float64Array): number {- const node = this.nodes++;- const [boxes, order, corners] = [this.boxes, this.order, this.corners];- const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];- const cLo = [Infinity, Infinity, Infinity], cHi = [-Infinity, -Infinity, -Infinity];- for (let i = first; i < first + count; i++) {- const t = order[i]!;- for (let k = 0; k < 3; k++) {- for (let c = 0; c < 3; c++) {- const x = corners[t * 9 + c * 3 + k]!;- if (x < lo[k]!) lo[k] = x;- if (x > hi[k]!) hi[k] = x;- }- const m = centers[t * 3 + k]!;- if (m < cLo[k]!) cLo[k] = m;- if (m > cHi[k]!) cHi[k] = m;- }- }- for (let k = 0; k < 3; k++) { boxes[node * 6 + k] = lo[k]!; boxes[node * 6 + 3 + k] = hi[k]!; }- const axis = cHi[0]! - cLo[0]! >= cHi[1]! - cLo[1]! && cHi[0]! - cLo[0]! >= cHi[2]! - cLo[2]! ? 0 : cHi[1]! - cLo[1]! >= cHi[2]! - cLo[2]! ? 1 : 2;- if (count <= LEAF || cHi[axis]! - cLo[axis]! <= 0) {- this.links[node * 2] = first;- this.links[node * 2 + 1] = count;- return node;- }- const half = (cLo[axis]! + cHi[axis]!) / 2;- let split = first;- for (let i = first; i < first + count; i++) {- if (centers[order[i]! * 3 + axis]! < half) {- const swap = order[i]!;- order[i] = order[split]!;- order[split] = swap;- split++;- }- }- this.build(first, split - first, centers);- this.links[node * 2] = this.build(split, first + count - split, centers);- this.links[node * 2 + 1] = 0;- return node;- }-- /**- * The hit on the line through @p o along @p d nearest to @p o, within @p reach either way, on a triangle- * facing along @p d. Answers its triangle, or -1; the place on it goes in @p out as [u, v] for its 2nd and 3rd corners.- */- nearest(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, reach: number, out: Float64Array): number {- const [boxes, links, order, c, stack] = [this.boxes, this.links, this.order, this.corners, this.stack];- let best = reach, found = -1, top = 0;- stack[top++] = 0;- while (top > 0) {- const node = stack[--top]!;- const at = node * 6;- let near = -best, far = best;- let inside = true;- for (let k = 0; k < 3 && inside; k++) {- const d = k === 0 ? dx : k === 1 ? dy : dz, o = k === 0 ? ox : k === 1 ? oy : oz;- const lo = boxes[at + k]!, hi = boxes[at + 3 + k]!;- if (d === 0) { inside = o >= lo && o <= hi; continue; }- let t0 = (lo - o) / d, t1 = (hi - o) / d;- if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }- if (t0 > near) near = t0;- if (t1 < far) far = t1;- inside = near <= far;- }- if (!inside) continue;- const count = links[node * 2 + 1]!;- if (count === 0) {- stack[top++] = links[node * 2]!;- stack[top++] = node + 1;- continue;- }- const first = links[node * 2]!;- for (let i = first; i < first + count; i++) {- const t = order[i]!, p = t * 9;- const ax = c[p]!, ay = c[p + 1]!, az = c[p + 2]!;- const e1x = c[p + 3]! - ax, e1y = c[p + 4]! - ay, e1z = c[p + 5]! - az;- const e2x = c[p + 6]! - ax, e2y = c[p + 7]! - ay, e2z = c[p + 8]! - az;- const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;- const det = e1x * px + e1y * py + e1z * pz;- // Negative is the line running along the triangle's outward normal: the inner wall of a thin part is not this surface.- if (det > -1e-14) continue;- const inv = 1 / det;- const sx = ox - ax, sy = oy - ay, sz = oz - az;- const u = (sx * px + sy * py + sz * pz) * inv;- if (u < 0 || u > 1) continue;- const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;- const v = (dx * qx + dy * qy + dz * qz) * inv;- if (v < 0 || u + v > 1) continue;- const along = (e2x * qx + e2y * qy + e2z * qz) * inv;- if (Math.abs(along) < best) {- best = Math.abs(along);- found = t;- out[0] = u;- out[1] = v;- }- }- }- return found;- }-- /** Whether anything lies on the ray from @p o along @p d within @p reach, whichever way it faces. */- blocked(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, reach: number): boolean {- const [boxes, links, order, c, stack] = [this.boxes, this.links, this.order, this.corners, this.stack];- let top = 0;- stack[top++] = 0;- while (top > 0) {- const node = stack[--top]!;- const at = node * 6;- let near = 0, far = reach;- let inside = true;- for (let k = 0; k < 3 && inside; k++) {- const d = k === 0 ? dx : k === 1 ? dy : dz, o = k === 0 ? ox : k === 1 ? oy : oz;- const lo = boxes[at + k]!, hi = boxes[at + 3 + k]!;- if (d === 0) { inside = o >= lo && o <= hi; continue; }- let t0 = (lo - o) / d, t1 = (hi - o) / d;- if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }- if (t0 > near) near = t0;- if (t1 < far) far = t1;- inside = near <= far;- }- if (!inside) continue;- const count = links[node * 2 + 1]!;- if (count === 0) {- stack[top++] = links[node * 2]!;- stack[top++] = node + 1;- continue;- }- const first = links[node * 2]!;- for (let i = first; i < first + count; i++) {- const p = order[i]! * 9;- const ax = c[p]!, ay = c[p + 1]!, az = c[p + 2]!;- const e1x = c[p + 3]! - ax, e1y = c[p + 4]! - ay, e1z = c[p + 5]! - az;- const e2x = c[p + 6]! - ax, e2y = c[p + 7]! - ay, e2z = c[p + 8]! - az;- const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;- const det = e1x * px + e1y * py + e1z * pz;- if (det > -1e-14 && det < 1e-14) continue;- const inv = 1 / det;- const sx = ox - ax, sy = oy - ay, sz = oz - az;- const u = (sx * px + sy * py + sz * pz) * inv;- if (u < 0 || u > 1) continue;- const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;- const v = (dx * qx + dy * qy + dz * qz) * inv;- if (v < 0 || u + v > 1) continue;- const along = (e2x * qx + e2y * qy + e2z * qz) * inv;- if (along > 0 && along < reach) return true;- }- }- return false;- }-}-/** Every texel centre inside a triangle of the mesh, with the triangle's corners and how much of each it is. */function rasterTexels(indices: ArrayLike<number>, UV: Float32Array, size: number,diff --git a/pipeline/src/modeling/polyMesh.ts b/pipeline/src/modeling/polyMesh.tsindex 74d6a30d9..360dd56e5 100644--- a/pipeline/src/modeling/polyMesh.ts+++ b/pipeline/src/modeling/polyMesh.ts@@ -22,6 +22,10 @@ export interface Face {roughness?: number;/** How much metal, 0..1. Absent takes the source's `material`. */metallic?: number;+ /** The hair card this is part of, with `cornerUvs` where its texture lands. */+ card?: number;+ /** A texture's place at each corner, in the order of `v`, in place of any projection. */+ cornerUvs?: readonly (readonly [number, number])[];/** Part of a continuous skin: shaded smooth with its neighbours whatever the angle, and its edges are not features. */smooth?: boolean;/** How this face takes its texture, from a `uv` step; absent, a box projection at the source's uvScale. */diff --git a/pipeline/src/modeling/rig.ts b/pipeline/src/modeling/rig.tsindex ddbc58013..fc71865d7 100644--- a/pipeline/src/modeling/rig.ts+++ b/pipeline/src/modeling/rig.ts@@ -930,16 +930,18 @@ export function timelineOf(animation: AnimationSource, joints: readonly RigJoint* The prefab that draws and moves it: the mesh on the root, the joints below it as* entities named so a clip's paths find them, and a player for the first clip.*/-export function prefabOf(name: string, meshPath: string, joints: readonly RigJoint[], cullBackfaces: boolean, firstClip: string | null, controller: string | null = null, extra: { goals?: readonly RigGoal[]; shapes?: number; normalMap?: string; texture?: string; material?: string } = {}): Record<string, unknown> {+const SWAY_COLLIDER = 'hairCollider';++export function prefabOf(name: string, meshPath: string, joints: readonly RigJoint[], cullBackfaces: boolean, firstClip: string | null, controller: string | null = null, extra: { goals?: readonly RigGoal[]; shapes?: number; normalMap?: string; texture?: string; material?: string; opaque?: boolean; sway?: { chainRoots: readonly number[]; stiffness?: number; drag?: number; collider?: { at: Vec3; radius: number } } } = {}): Record<string, unknown> {const idOf = (i: number): string => `j${i}`;const goals = extra.goals ?? [];const entities: Record<string, unknown>[] = [{prefabEntityId: 'root', name, parent: null,- children: [...joints.flatMap((j, i) => (j.parent < 0 ? [idOf(i)] : [])), ...goals.flatMap((g, i) => (g.parent === undefined ? [`g${i}`] : []))],+ children: [...joints.flatMap((j, i) => (j.parent < 0 ? [idOf(i)] : [])), ...goals.flatMap((g, i) => (g.parent === undefined ? [`g${i}`] : [])), ...(extra.sway?.collider ? [SWAY_COLLIDER] : [])],visible: true,components: [{ type: 'Transform', data: {} },- { type: 'MeshRenderer', data: { mesh: meshPath, ...(extra.normalMap ? { normalMap: extra.normalMap } : {}), ...(extra.texture ? { texture: extra.texture } : {}), ...(extra.material ? { material: extra.material } : {}), lit: true, opaque: true, cullBackfaces, enabled: true } },+ { type: 'MeshRenderer', data: { mesh: meshPath, ...(extra.normalMap ? { normalMap: extra.normalMap } : {}), ...(extra.texture ? { texture: extra.texture } : {}), ...(extra.material ? { material: extra.material } : {}), lit: true, opaque: extra.opaque ?? true, cullBackfaces, enabled: true } },...(joints.length ? [{ type: 'MeshSkin', data: { joints: joints.map((_, i) => idOf(i)) } }] : []),...(extra.shapes ? [{ type: 'MeshMorph', data: { weights: Array.from({ length: extra.shapes }, () => 0) } }] : []),// A controller decides what plays; a player beside it would fight it for the same joints.@@ -952,9 +954,23 @@ export function prefabOf(name: string, meshPath: string, joints: readonly RigJoientities.push({prefabEntityId: idOf(i), name: j.name, parent: j.parent >= 0 ? idOf(j.parent) : 'root',children: [...j.children.map(idOf), ...goals.flatMap((g, k) => (g.parent === j.name ? [`g${k}`] : []))], visible: true,- components: [{ type: 'Transform', data: { position: { x: rest[0], y: rest[1], z: rest[2] } } }],+ components: [+ { type: 'Transform', data: { position: { x: rest[0], y: rest[1], z: rest[2] } } },+ // On a chain's first bone, which stays where it is: the ones below it swing.+ ...(extra.sway?.chainRoots.includes(i) ? [{ type: 'SpringBone', data: {+ enabled: true, stiffness: extra.sway.stiffness ?? 0.08, drag: extra.sway.drag ?? 0.3,+ ...(extra.sway.collider ? { colliders: [SWAY_COLLIDER] } : {}),+ } }] : []),+ ],});});+ if (extra.sway?.collider) {+ const { at, radius } = extra.sway.collider;+ entities.push({+ prefabEntityId: SWAY_COLLIDER, name: 'hair collider', parent: 'root', children: [], visible: true,+ components: [{ type: 'Transform', data: { position: { x: at[0], y: at[1], z: at[2] } } }, { type: 'SpringBoneCollider', data: { shape: 0, radius } }],+ });+ }goals.forEach((g, i) => {const parent = g.parent === undefined ? -1 : joints.findIndex((j) => j.name === g.parent);const rest = parent >= 0 ? sub(g.at, joints[parent]!.at) : g.at;diff --git a/pipeline/src/modeling/stain.ts b/pipeline/src/modeling/stain.tsindex 581326c86..7033df72a 100644--- a/pipeline/src/modeling/stain.ts+++ b/pipeline/src/modeling/stain.ts@@ -22,6 +22,8 @@ export interface StainParams {roughness?: number;/** How much metal to make it, 0..1: bare steel where the paint has worn off. */metallic?: number;+ /** How solid to make it, 0..1: 0 is a hole, under a material with `alpha`. */+ alpha?: number;/** How strongly, 0..1, where the rest say all the way. Default 1. */amount?: number;pattern?: DisplacePattern;@@ -106,9 +108,9 @@ function relief(mesh: PolyMesh, normals: Float64Array, reach: number | undefined}export function stain(mesh: PolyMesh, p: StainParams, budget = MAX_DISPLACE_TRIANGLES, surfaceDefaults?: { roughness: number; metallic: number }): PolyMesh {- if (p.color === undefined && p.roughness === undefined && p.metallic === undefined) throw new Error('give at least one of color, roughness, metallic');+ if (p.color === undefined && p.roughness === undefined && p.metallic === undefined && p.alpha === undefined) throw new Error('give at least one of color, roughness, metallic, alpha');if (p.color !== undefined && p.color.length < 3) throw new Error('color must be [r, g, b]');- for (const [name, v] of [['roughness', p.roughness], ['metallic', p.metallic]] as const) {+ for (const [name, v] of [['roughness', p.roughness], ['metallic', p.metallic], ['alpha', p.alpha]] as const) {if (v !== undefined && !(v >= 0 && v <= 1)) throw new Error(`${name} ${v} must be 0..1`);}if (p.pattern !== undefined && !DISPLACE_PATTERNS.includes(p.pattern)) throw new Error(`pattern ${JSON.stringify(p.pattern)} must be one of ${DISPLACE_PATTERNS.join(', ')}`);@@ -191,7 +193,12 @@ export function stain(mesh: PolyMesh, p: StainParams, budget = MAX_DISPLACE_TRIAconst was = face.color ?? [1, 1, 1, 1];return {...face,- ...(color ? { color: [was[0] + (color[0] - was[0]) * m, was[1] + (color[1] - was[1]) * m, was[2] + (color[2] - was[2]) * m, was[3]] as const } : {}),+ ...(color || p.alpha !== undefined ? {+ color: [+ was[0] + ((color?.[0] ?? was[0]) - was[0]) * m, was[1] + ((color?.[1] ?? was[1]) - was[1]) * m, was[2] + ((color?.[2] ?? was[2]) - was[2]) * m,+ was[3] + ((p.alpha ?? was[3]) - was[3]) * m,+ ] as const,+ } : {}),...(p.roughness !== undefined ? { roughness: (face.roughness ?? defaults.roughness) + (p.roughness - (face.roughness ?? defaults.roughness)) * m } : {}),...(p.metallic !== undefined ? { metallic: (face.metallic ?? defaults.metallic) + (p.metallic - (face.metallic ?? defaults.metallic)) * m } : {}),};diff --git a/pipeline/src/modeling/triangleTree.ts b/pipeline/src/modeling/triangleTree.tsnew file mode 100644index 000000000..92c4b5e06--- /dev/null+++ b/pipeline/src/modeling/triangleTree.ts@@ -0,0 +1,190 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** @file triangleTree.ts — rays against a surface: what a bake reads a dense model through, and what keeps hair out of a head. */+import { triangulateFace } from './triangulate';+import type { PolyMesh } from './polyMesh';++const LEAF = 4;++/** A mesh's triangles as a tree reads them: nine numbers each, three corners. */+export function trianglesOf(mesh: PolyMesh): Float64Array {+ const out: number[] = [];+ for (const face of mesh.faces) {+ for (const tri of triangulateFace(mesh, face)) {+ for (const v of tri) { const p = mesh.positions[v]!; out.push(p[0], p[1], p[2]); }+ }+ }+ return Float64Array.from(out);+}++/** A bounding-volume hierarchy over triangles, in flat arrays: a dense model is several hundred thousand of them. */+export class TriangleTree {+ private readonly order: Int32Array;+ private readonly boxes: Float64Array;+ /** Per node: a leaf's first triangle in `order` and its count, or the right child and 0. */+ private readonly links: Int32Array;+ private nodes = 0;+ private readonly stack = new Int32Array(128);++ constructor(private readonly corners: Float64Array) {+ const count = corners.length / 9;+ this.order = Int32Array.from({ length: count }, (_, i) => i);+ this.boxes = new Float64Array(count * 2 * 6 + 6);+ this.links = new Int32Array(count * 2 * 2 + 2);+ const centers = new Float64Array(count * 3);+ for (let t = 0; t < count; t++) {+ for (let k = 0; k < 3; k++) centers[t * 3 + k] = (corners[t * 9 + k]! + corners[t * 9 + 3 + k]! + corners[t * 9 + 6 + k]!) / 3;+ }+ this.build(0, count, centers);+ }++ private build(first: number, count: number, centers: Float64Array): number {+ const node = this.nodes++;+ const [boxes, order, corners] = [this.boxes, this.order, this.corners];+ const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];+ const cLo = [Infinity, Infinity, Infinity], cHi = [-Infinity, -Infinity, -Infinity];+ for (let i = first; i < first + count; i++) {+ const t = order[i]!;+ for (let k = 0; k < 3; k++) {+ for (let c = 0; c < 3; c++) {+ const x = corners[t * 9 + c * 3 + k]!;+ if (x < lo[k]!) lo[k] = x;+ if (x > hi[k]!) hi[k] = x;+ }+ const m = centers[t * 3 + k]!;+ if (m < cLo[k]!) cLo[k] = m;+ if (m > cHi[k]!) cHi[k] = m;+ }+ }+ for (let k = 0; k < 3; k++) { boxes[node * 6 + k] = lo[k]!; boxes[node * 6 + 3 + k] = hi[k]!; }+ const axis = cHi[0]! - cLo[0]! >= cHi[1]! - cLo[1]! && cHi[0]! - cLo[0]! >= cHi[2]! - cLo[2]! ? 0 : cHi[1]! - cLo[1]! >= cHi[2]! - cLo[2]! ? 1 : 2;+ if (count <= LEAF || cHi[axis]! - cLo[axis]! <= 0) {+ this.links[node * 2] = first;+ this.links[node * 2 + 1] = count;+ return node;+ }+ const half = (cLo[axis]! + cHi[axis]!) / 2;+ let split = first;+ for (let i = first; i < first + count; i++) {+ if (centers[order[i]! * 3 + axis]! < half) {+ const swap = order[i]!;+ order[i] = order[split]!;+ order[split] = swap;+ split++;+ }+ }+ this.build(first, split - first, centers);+ this.links[node * 2] = this.build(split, first + count - split, centers);+ this.links[node * 2 + 1] = 0;+ return node;+ }++ /**+ * The hit on the line through @p o along @p d nearest to @p o, within @p reach either way, on a triangle+ * facing along @p d. Answers its triangle, or -1; the place on it goes in @p out as [u, v] for its 2nd and 3rd corners.+ */+ nearest(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, reach: number, out: Float64Array): number {+ const [boxes, links, order, c, stack] = [this.boxes, this.links, this.order, this.corners, this.stack];+ let best = reach, found = -1, top = 0;+ stack[top++] = 0;+ while (top > 0) {+ const node = stack[--top]!;+ const at = node * 6;+ let near = -best, far = best;+ let inside = true;+ for (let k = 0; k < 3 && inside; k++) {+ const d = k === 0 ? dx : k === 1 ? dy : dz, o = k === 0 ? ox : k === 1 ? oy : oz;+ const lo = boxes[at + k]!, hi = boxes[at + 3 + k]!;+ if (d === 0) { inside = o >= lo && o <= hi; continue; }+ let t0 = (lo - o) / d, t1 = (hi - o) / d;+ if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }+ if (t0 > near) near = t0;+ if (t1 < far) far = t1;+ inside = near <= far;+ }+ if (!inside) continue;+ const count = links[node * 2 + 1]!;+ if (count === 0) {+ stack[top++] = links[node * 2]!;+ stack[top++] = node + 1;+ continue;+ }+ const first = links[node * 2]!;+ for (let i = first; i < first + count; i++) {+ const t = order[i]!, p = t * 9;+ const ax = c[p]!, ay = c[p + 1]!, az = c[p + 2]!;+ const e1x = c[p + 3]! - ax, e1y = c[p + 4]! - ay, e1z = c[p + 5]! - az;+ const e2x = c[p + 6]! - ax, e2y = c[p + 7]! - ay, e2z = c[p + 8]! - az;+ const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;+ const det = e1x * px + e1y * py + e1z * pz;+ // Negative is the line running along the triangle's outward normal: the inner wall of a thin part is not this surface.+ if (det > -1e-14) continue;+ const inv = 1 / det;+ const sx = ox - ax, sy = oy - ay, sz = oz - az;+ const u = (sx * px + sy * py + sz * pz) * inv;+ if (u < 0 || u > 1) continue;+ const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;+ const v = (dx * qx + dy * qy + dz * qz) * inv;+ if (v < 0 || u + v > 1) continue;+ const along = (e2x * qx + e2y * qy + e2z * qz) * inv;+ if (Math.abs(along) < best) {+ best = Math.abs(along);+ found = t;+ out[0] = u;+ out[1] = v;+ }+ }+ }+ return found;+ }++ /** Whether anything lies on the ray from @p o along @p d within @p reach, whichever way it faces. */+ blocked(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, reach: number): boolean {+ const [boxes, links, order, c, stack] = [this.boxes, this.links, this.order, this.corners, this.stack];+ let top = 0;+ stack[top++] = 0;+ while (top > 0) {+ const node = stack[--top]!;+ const at = node * 6;+ let near = 0, far = reach;+ let inside = true;+ for (let k = 0; k < 3 && inside; k++) {+ const d = k === 0 ? dx : k === 1 ? dy : dz, o = k === 0 ? ox : k === 1 ? oy : oz;+ const lo = boxes[at + k]!, hi = boxes[at + 3 + k]!;+ if (d === 0) { inside = o >= lo && o <= hi; continue; }+ let t0 = (lo - o) / d, t1 = (hi - o) / d;+ if (t0 > t1) { const s = t0; t0 = t1; t1 = s; }+ if (t0 > near) near = t0;+ if (t1 < far) far = t1;+ inside = near <= far;+ }+ if (!inside) continue;+ const count = links[node * 2 + 1]!;+ if (count === 0) {+ stack[top++] = links[node * 2]!;+ stack[top++] = node + 1;+ continue;+ }+ const first = links[node * 2]!;+ for (let i = first; i < first + count; i++) {+ const p = order[i]! * 9;+ const ax = c[p]!, ay = c[p + 1]!, az = c[p + 2]!;+ const e1x = c[p + 3]! - ax, e1y = c[p + 4]! - ay, e1z = c[p + 5]! - az;+ const e2x = c[p + 6]! - ax, e2y = c[p + 7]! - ay, e2z = c[p + 8]! - az;+ const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;+ const det = e1x * px + e1y * py + e1z * pz;+ if (det > -1e-14 && det < 1e-14) continue;+ const inv = 1 / det;+ const sx = ox - ax, sy = oy - ay, sz = oz - az;+ const u = (sx * px + sy * py + sz * pz) * inv;+ if (u < 0 || u > 1) continue;+ const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;+ const v = (dx * qx + dy * qy + dz * qz) * inv;+ if (v < 0 || u + v > 1) continue;+ const along = (e2x * qx + e2y * qy + e2z * qz) * inv;+ if (along > 0 && along < reach) return true;+ }+ }+ return false;+ }+}diff --git a/pipeline/tests/modeling-hair.test.ts b/pipeline/tests/modeling-hair.test.tsnew file mode 100644index 000000000..012a704ed--- /dev/null+++ b/pipeline/tests/modeling-hair.test.ts@@ -0,0 +1,245 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** Cards of hair, the textures they are cut from, the bones that swing them, and holes in a surface. */+import { describe, expect, it } from 'vitest';+import { MeshChannel } from 'esengine';+import { bakeModel, bakeNormalMap, modelMaterialDoc, validateModelSource, type BakedModel, type ModelStep } from '../src/modeling';+import { hairMaps } from '../src/modeling/hair';++const head: ModelStep = { op: 'sphere', radius: 1, rings: 24, sides: 48, tag: 'head' };+const scalp = { within: { min: [null, 0.2, null] } };+const hair = (extra: Record<string, unknown> = {}): BakedModel => bakeModel({ version: 1, steps: [head, { op: 'hair', faces: scalp, count: 60, length: 1.4, ...extra }] });++describe('hair', () => {+ it('gives each card a ribbon of quads, and drops what they grew from', () => {+ const m = hair({ segments: 5 });+ expect(m.poly.faces).toHaveLength(60 * 5);+ expect(m.poly.positions).toHaveLength(60 * 6 * 2);+ for (const f of m.poly.faces) { expect(f.card).toBeGreaterThanOrEqual(0); expect(f.v).toHaveLength(4); }+ expect(m.report.tags).toEqual({ hair: 300 });+ });++ it('adds a layer each time, the second falling over the first, and keeps only cards in the end', () => {+ const one = hair({ segments: 4 });+ const two = bakeModel({ version: 1, steps: [head, { op: 'hair', faces: scalp, count: 60, length: 1.4, segments: 4 }, { op: 'hair', faces: scalp, count: 40, length: 0.7, segments: 4, seed: 2 }] });+ expect(one.poly.faces).toHaveLength(240);+ expect(two.poly.faces).toHaveLength(400);+ expect(new Set(two.poly.faces.map((f) => f.card)).size).toBe(100);+ expect(two.report.tags).toEqual({ hair: 400 });+ expect(two.report.warnings).toEqual([]);+ });++ it('starts on the scalp and stays out of the head: no vertex goes far inside it', () => {+ const m = hair({ count: 150, droop: 1 });+ let inside = 0;+ for (const p of m.poly.positions) if (Math.hypot(p[0], p[1], p[2]) < 0.93) inside++;+ expect(inside / m.poly.positions.length).toBeLessThan(0.01);+ // Roots: the first row of each card.+ const roots = m.poly.faces.filter((_, i) => i % 6 === 0).map((f) => m.poly.positions[f.v[0]!]!);+ for (const q of roots) { expect(Math.hypot(q[0], q[1], q[2])).toBeLessThan(1.15); expect(q[1]).toBeGreaterThan(0.15); }+ });++ it('`droop` decides how far it falls', () => {+ const lowest = (m: BakedModel): number => m.poly.positions.reduce((lo, p) => Math.min(lo, p[1]), Infinity);+ expect(lowest(hair({ droop: 1 }))).toBeLessThan(lowest(hair({ droop: 0.1 })) - 0.3);+ });++ it('`comb` sweeps it that way', () => {+ const meanZ = (m: BakedModel): number => m.poly.positions.reduce((sum, p) => sum + p[2], 0) / m.poly.positions.length;+ expect(meanZ(hair({ comb: [0, 0, -1] }))).toBeLessThan(meanZ(hair()) - 0.3);+ });++ it('`length` and `uneven` set how long a card is', () => {+ const longest = (m: BakedModel): number => {+ const cards = new Map<number, number>();+ for (const f of m.poly.faces) {+ const [a, b] = [m.poly.positions[f.v[0]!]!, m.poly.positions[f.v[1]!]!];+ cards.set(f.card!, (cards.get(f.card!) ?? 0) + Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]));+ }+ return Math.max(...cards.values());+ };+ expect(longest(hair({ length: 2, uneven: 0 }))).toBeGreaterThan(longest(hair({ length: 1, uneven: 0 })) * 1.8);+ });++ it('narrows to the tip, by `taper`', () => {+ const m = hair({ count: 1, segments: 4, taper: 0.8, width: 0.2 });+ const across = (i: number, j: number, face: number): number => {+ const v = m.poly.faces[face]!.v;+ const [a, b] = [m.poly.positions[v[i]!]!, m.poly.positions[v[j]!]!];+ return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);+ };+ expect(across(0, 3, 0)).toBeCloseTo(0.2, 3);+ expect(across(1, 2, 3)).toBeCloseTo(0.04, 3);+ });++ it('runs from `color` to `tipColor`', () => {+ const m = hair({ count: 1, segments: 4, color: [1, 0, 0], tipColor: [0, 0, 1] });+ expect(m.poly.faces[0]!.color![0]).toBeGreaterThan(0.8);+ expect(m.poly.faces[3]!.color![2]).toBeGreaterThan(0.8);+ });++ it('is the same every time, and a seed makes another', () => {+ expect(hair().poly.positions).toEqual(hair().poly.positions);+ expect(hair({ seed: 5 }).poly.positions).not.toEqual(hair().poly.positions);+ });++ it('lands each card inside one strip of the texture, root at its top row', () => {+ const m = hair();+ const { offset } = m.data.channels.find((c) => c.semantic === MeshChannel.TexCoord0)!;+ const view = new DataView(m.data.vertices.buffer, m.data.vertices.byteOffset, m.data.vertices.byteLength);+ for (let v = 0; v < m.data.vertexCount; v++) {+ const [a, b] = [view.getFloat32(v * m.data.vertexStride + offset, true), view.getFloat32(v * m.data.vertexStride + offset + 4, true)];+ expect(a).toBeGreaterThanOrEqual(0); expect(a).toBeLessThanOrEqual(1);+ expect(b).toBeGreaterThanOrEqual(0); expect(b).toBeLessThanOrEqual(1);+ }+ const face = m.poly.faces[0]!;+ const [u0, u1] = [face.cornerUvs![0]![0], face.cornerUvs![2]![0]];+ expect(Math.floor(u0 * 4)).toBe(Math.floor(u1 * 4));+ });++ it('carries a frame for the map it reads, and no lightmap layout', () => {+ const m = hair();+ expect(m.data.channels.some((c) => c.semantic === MeshChannel.Tangent)).toBe(true);+ expect(m.data.channels.some((c) => c.semantic === MeshChannel.TexCoord1)).toBe(false);+ });++ it('refuses what cannot be meant', () => {+ const steps = [head, { op: 'hair', faces: scalp, length: 1 }];+ expect(() => bakeModel({ version: 1, steps: [head, { op: 'hair', faces: 'nothing', length: 1 }] })).toThrow(/matched no face/);+ expect(() => bakeModel({ version: 1, steps: [head, { op: 'hair', faces: scalp, length: -1 }] })).toThrow(/length -1 must be positive/);+ expect(() => bakeModel({ version: 1, steps: [head, { op: 'hair', faces: scalp, length: 1, droop: 2 }] })).toThrow(/droop 2 must be 0..1/);+ expect(() => validateModelSource({ steps: [head, { op: 'hair', faces: scalp }] })).toThrow(/length is required/);+ expect(() => validateModelSource({ steps, normalBake: { from: 'x' } })).toThrow(/no normalBake or uvAtlas/);+ expect(() => validateModelSource({ steps, rig: { joints: [{ name: 'a', at: [0, 0, 0] }] } })).toThrow(/no rig or shapes/);+ });+});++describe('the strand textures', () => {+ const maps = hairMaps();+ const size = maps.strands.size;+ const alphaAt = (x: number, y: number): number => maps.strands.rgba[(y * size + x) * 4 + 3]!;++ it('are strands: gaps between them across a card, and solid where they run together', () => {+ const row = Math.floor(size * 0.25);+ let solid = 0, clear = 0, edges = 0;+ for (let x = 0; x < size / 4; x++) {+ const a = alphaAt(x, row);+ if (a > 200) solid++;+ if (a < 30) clear++;+ if (x > 0 && (a > 128) !== (alphaAt(x - 1, row) > 128)) edges++;+ }+ expect(solid).toBeGreaterThan(5);+ expect(clear).toBeGreaterThan(5);+ expect(edges).toBeGreaterThan(6);+ });++ it('thin out toward the tips, which are at the bottom rows', () => {+ const covered = (y: number): number => { let n = 0; for (let x = 0; x < size; x++) if (alphaAt(x, y) > 128) n++; return n; };+ expect(covered(Math.floor(size * 0.1))).toBeGreaterThan(covered(Math.floor(size * 0.9)) * 3);+ expect(covered(size - 1)).toBe(0);+ });++ it('keep clear at the edges of each strip, so a card\'s side has no hard line', () => {+ for (let y = 0; y < size; y += 16) for (const x of [0, size / 4 - 1, size / 4, size / 2 - 1]) expect(alphaAt(x, y)).toBe(0);+ });++ it('point along v in the flow map, and differ from place to place in the shift map', () => {+ expect([...maps.flow.rgba.subarray(0, 4)]).toEqual([128, 255, 128, 255]);+ const tones = new Set<number>();+ for (let i = 0; i < 256; i++) tones.add(maps.shift.rgba[i * 4]!);+ expect(tones.size).toBeGreaterThan(30);+ });+});++describe('hairSway', () => {+ const swung = (sway: Record<string, unknown> = {}): BakedModel => bakeModel({ version: 1, hairSway: { chains: 6, bones: 3, ...sway }, steps: [head, { op: 'hair', faces: scalp, count: 60, length: 1.4 }] });++ it('makes a root and a chain of joints per group of cards', () => {+ const m = swung();+ expect(m.rig!.joints).toHaveLength(1 + 6 * 4);+ expect(m.rig!.joints[0]!.name).toBe('hair');+ expect(m.hair!.chainRoots).toHaveLength(6);+ for (const root of m.hair!.chainRoots!) expect(m.rig!.joints[root]!.parent).toBe(0);+ });++ it('runs each chain down the cards it owns', () => {+ const m = swung();+ for (const root of m.hair!.chainRoots!) {+ const [top, bottom] = [m.rig!.joints[root]!.at, m.rig!.joints[root + 3]!.at];+ expect(Math.hypot(top[0] - bottom[0], top[1] - bottom[1], top[2] - bottom[2])).toBeGreaterThan(0.3);+ }+ });++ it('binds each vertex wholly, to the two bones either side of it, and the roots to the first', () => {+ const m = swung();+ const { joints, weights } = m.rig!.skin;+ for (let v = 0; v < m.poly.positions.length; v++) {+ expect(weights[v * 4]! + weights[v * 4 + 1]!).toBeCloseTo(1, 5);+ expect(weights[v * 4 + 2]).toBe(0);+ expect(joints[v * 4 + 1]).toBe(joints[v * 4]! + 1);+ }+ for (const root of m.hair!.chainRoots!) expect(m.rig!.skin.dominant[root]).toBeGreaterThan(0);+ });++ it('puts every joint on the skin\'s joints channel', () => {+ expect(swung().data.channels.some((c) => c.semantic === MeshChannel.Joints)).toBe(true);+ });++ it('refuses what cannot be meant', () => {+ expect(() => validateModelSource({ steps: [head], hairSway: {} })).toThrow(/needs a hair step/);+ const steps = [head, { op: 'hair', faces: scalp, length: 1 }];+ expect(() => validateModelSource({ steps, hairSway: { chains: 0 } })).toThrow(/chains must be 1..60/);+ expect(() => validateModelSource({ steps, hairSway: { stiffness: 2 } })).toThrow(/stiffness must be 0..1/);+ expect(() => validateModelSource({ steps, hairSway: { collider: { at: [0, 0] } } })).toThrow(/collider must be/);+ expect(() => validateModelSource({ steps, hairSway: { swing: 1 } })).toThrow(/unknown field "swing"/);+ });+});++describe('see-through', () => {+ const plane: ModelStep = { id: 'form', op: 'plane', size: 2, color: [0.2, 0.6, 0.2] };++ it('a stain sets alpha where it lands, and keeps the colour', () => {+ const m = bakeModel({ version: 1, material: { alpha: 'cutout' }, steps: [plane, { op: 'stain', near: { at: [0, 0, 0], radius: 0.5 }, hard: true, alpha: 0, detail: 0.1 }] });+ const holes = m.poly.faces.filter((f) => f.color![3] === 0);+ expect(holes.length).toBeGreaterThan(5);+ for (const f of m.poly.faces) expect(f.color![1]).toBeCloseTo(0.6, 5);+ });++ it('a bake keeps holes on a mesh that has no triangles for them', () => {+ const m = bakeModel({ version: 1, material: { alpha: 'cutout' }, normalBake: { size: 128, color: true }, steps: [plane, { op: 'stain', near: { at: [0, 0, 0], radius: 0.5 }, hard: true, alpha: 0, detail: 0.05 }, { op: 'decimate', from: 'form', ratio: 1 }] });+ expect(m.report.triangles).toBe(2);+ const { colorRgba } = bakeNormalMap(m);+ let clear = 0, solid = 0;+ for (let i = 3; i < colorRgba!.length; i += 4) { if (colorRgba![i] === 0) clear++; if (colorRgba![i] === 255) solid++; }+ expect(clear).toBeGreaterThan(500);+ expect(solid).toBeGreaterThan(clear);+ });++ it('writes a cutout unblended, with its cutoff, both sides drawn', () => {+ const doc = modelMaterialDoc(validateModelSource({ steps: [plane], material: { alpha: 'cutout', cutoff: 0.3 } }), true, {})!;+ expect((doc.properties as Record<string, unknown>).u_alphaCutoff).toBe(0.3);+ expect(doc.depthWrite).toBe(true);+ expect(doc.cull).toBe(modelMaterialDoc(validateModelSource({ steps: [plane], material: {} }), false, {})!.cull);+ });++ it('writes a blend blended, not writing depth', () => {+ const blend = modelMaterialDoc(validateModelSource({ steps: [plane], material: { alpha: 'blend' } }), true, {})!;+ const plain = modelMaterialDoc(validateModelSource({ steps: [plane], material: { metallic: 1 } }), true, {})!;+ expect(blend.depthWrite).toBe(false);+ expect(blend.blendMode).not.toBe(plain.blendMode);+ });++ it('a hair material is the Hair shader, cut out, with both sides drawn and the maps it reads', () => {+ const doc = modelMaterialDoc(validateModelSource({ steps: [plane] }), false, { hair: { flow: 'a_flow.png', shift: 'a_shift.png' } })!;+ expect(doc.shader).toBe('builtin:hair');+ const p = doc.properties as Record<string, unknown>;+ expect(p.u_flowMap).toBe('a_flow.png');+ expect(p.u_shiftMap).toBe('a_shift.png');+ expect(p.u_alphaCutoff).toBeGreaterThan(0);+ });++ it('refuses an alpha it does not know', () => {+ expect(() => validateModelSource({ steps: [plane], material: { alpha: 'glass' } })).toThrow(/alpha must be cutout or blend/);+ expect(() => validateModelSource({ steps: [plane], material: { cutoff: 2 } })).toThrow(/cutoff must be 0..1/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex b3dda4b62..89232efca 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3882,6 +3882,10 @@ export const NOTED = {{"note":"A rotation given to an agent as a quaternion is that rotation."},"fix(asset): a map a material names keeps its import settings in Play, where it was decoded as colour":{"note":"A material's normal and metal-rough maps are read as data in the editor's Play."},+ "feat(modeling): a hair step grows cards from a scalp, and a material can cut holes or let light through":+ {"note":"An AI building a model can make hair."},+ "feat(mcp): model_write makes hair and see-through surfaces, and a check draws them":+ {"note":"An AI building a model can make things see-through."},"feat(modeling): a bake works out how much sky a dense surface sees, and shades its creases by it":{"note":"An AI building a model can shade its creases."},"feat(mcp): model_write bakes an occlusion map, and a check draws a groove with and without it":