prts-terrarchive 0.2.0

package/ui/rhine/original/motion.ts

@@ -0,0 +1,116 @@
+// Times are seconds from the reference video's 05:00 frame (25 fps).
+export const smooth = (t: number) => {
+  t = Math.max(0, Math.min(1, t));
+  return t * t * t * (10 + t * (-15 + 6 * t));
+};
+const bell = (x: number, width: number) => Math.exp(-0.5 * (x / width) ** 2);
+export function archiveWave(row: number, lane: number, time: number) {
+  const t = time - 22;
+  const phase = row + (lane - 2) * 0.65;
+  const enter = smooth(t / 0.32);
+  const first = 3 + t * 19;
+  const returning = 32 - (t - 2.3) * 24;
+  // A crest has shoulders and a trailing trough: neighboring files describe
+  // one continuous surface, rather than independent staggered tweens.
+  const packet = (distance: number) =>
+    2.5 * bell(distance, 3.8) - 0.58 * bell(distance - 6, 3.5);
+  return (
+    enter *
+    (packet(phase - first) * (1 - smooth((t - 2.15) / 0.65)) +
+      packet(phase - returning) *
+        smooth((t - 2.17) / 0.32) *
+        (1 - smooth((t - 3.5) / 0.85)))
+  );
+}
+export function extraction(time: number) {
+  return (
+    0.4 * smooth((time - 25.58) / 0.82) + 2.95 * smooth((time - 27.55) / 1.3)
+  );
+}
+// The returning scan leaves two moving shoulders around the selected file.
+// Their delay grows with distance, so the neighboring files keep moving during
+// the first extraction and settle before the second extraction.
+export function settlingWave(distance: number, time: number) {
+  const age = time - 25.05 - Math.abs(distance) * 0.065;
+  const envelope = Math.max(
+    -0.42,
+    2.15 - 0.17 * (Math.sqrt(distance * distance + 1) - 1),
+  );
+  const rise = smooth(age / 0.62);
+  const ring = age > 0 ? Math.sin(age * 5.1) * Math.exp(-age * 1.3) : 0;
+  return envelope * (rise + 0.18 * ring * smooth(age / 0.16));
+}
+export function baselineSelectionWave(distance: number, age: number) {
+  if (age < 0 || age > 3.2) return 0;
+  return (
+    0.8 *
+    smooth(age / 0.2) *
+    Math.exp(-age * 1.15) *
+    Math.cos((distance - age * 8) * 0.58) *
+    bell(distance - age * 8, 3.4)
+  );
+}
+
+// Retained for the comparison experiments; the user chose the signed baseline.
+export function selectionWave(distance: number, age: number) {
+  return Math.max(0, baselineSelectionWave(distance, age));
+}
+
+// The source stays still while the crest expands around it. Squaring the
+// positive cosine gives the ripple zero velocity at its leading/trailing edge.
+export function rippleEnvelope(distance: number, age: number) {
+  return (
+    smooth(distance / 2.5) * Math.max(0, Math.cos((distance - age * 8) * 0.58))
+  );
+}
+
+export function columnStrength(lane: number, focus: number, progress = 1) {
+  const selected = 0.25 + 0.75 * bell(lane - focus, 0.55);
+  return 1 + (selected - 1) * smooth(progress);
+}
+
+// A quiet idle drift, with neighboring cards slightly out of phase.
+// Maximum displacement is 0.102, under 3% of a card's height.
+export function idleWave(row: number, lane: number, time: number) {
+  return (
+    0.075 * Math.sin((time * Math.PI * 2) / 8 + row * 0.3 - lane * 0.45) +
+    0.027 * Math.sin((time * Math.PI * 2) / 13 - row * 0.17 + lane * 0.3)
+  );
+}
+
+export function cinematicField(
+  row: number,
+  lane: number,
+  time: number,
+  center = 12,
+  focus = 2,
+) {
+  const handoff = smooth((time - 24.95) / 0.45);
+  const selection = smooth((time - 25.4) / 0.95);
+  const shoulderTime = time + 0.3 * handoff * (1 - selection);
+  return (
+    archiveWave(row, lane, time) * (1 - handoff) +
+    settlingWave(row - center, shoulderTime) *
+      columnStrength(lane, focus, (time - 25.4) / 0.95)
+  );
+}
+
+export const INSPECTION_LIFT = 4.05;
+export const ALIGNMENT_EPSILON = 0.001;
+// Hold altitude while facing back into the slot. Descent begins only once
+// alignment is complete; this also applies to independently returning copies.
+export function returnStep(angle: number, dt: number, reduced = false) {
+  const next = angle * Math.exp(-dt * (reduced ? 35 : 7));
+  return Math.abs(next) <= ALIGNMENT_EPSILON ? 0 : next;
+}
+export interface Spring {
+  value: number;
+  velocity: number;
+}
+export function damp(s: Spring, target: number, rate: number, dt: number) {
+  const delta = s.value - target;
+  const impulse = s.velocity + rate * delta;
+  const decay = Math.exp(-rate * dt);
+  s.value = target + (delta + impulse * dt) * decay;
+  s.velocity = (s.velocity - rate * impulse * dt) * decay;
+}

package/ui/rhine/original/opaque-backfaces.ts

@@ -0,0 +1,64 @@
+import * as THREE from "three";
+
+const closed = new WeakMap<THREE.BufferGeometry, boolean>();
+
+/** Exact-position topology check, once during model preparation, never per frame. */
+function closedOutwardSurface(geometry: THREE.BufferGeometry) {
+  const cached = closed.get(geometry);
+  if (cached !== undefined) return cached;
+  const position = geometry.attributes.position, index = geometry.index, normal = geometry.attributes.normal;
+  if (!position || !index || !normal) return false;
+  const ids: number[] = [], parent: number[] = [], points: THREE.Vector3[] = [];
+  const weld = new Map<string, number>(), edges = new Map<string, { count: number; direction: number }>();
+  const faces: { vertex: number; volume: number }[] = [];
+  const find = (id: number): number => {
+    while (parent[id] !== id) { parent[id] = parent[parent[id]]; id = parent[id]; }
+    return id;
+  };
+  for (let i = 0; i < position.count; i++) {
+    const point = new THREE.Vector3().fromBufferAttribute(position, i), key = `${point.x},${point.y},${point.z}`;
+    let id = weld.get(key);
+    if (id === undefined) { id = parent.length; weld.set(key, id); parent.push(id); points.push(point); }
+    ids.push(id);
+  }
+  const cross = new THREE.Vector3(), edge = new THREE.Vector3(), normals = new THREE.Vector3(), n = new THREE.Vector3();
+  let valid = true;
+  for (let i = 0; i < index.count; i += 3) {
+    const raw = [index.getX(i), index.getX(i + 1), index.getX(i + 2)], vertices = raw.map(vertex => ids[vertex]);
+    const [a, b, c] = vertices.map(vertex => points[vertex]);
+    cross.copy(b).sub(a).cross(edge.copy(c).sub(a));
+    if (cross.lengthSq() < 1e-20) continue;
+    normals.set(0, 0, 0);
+    for (const vertex of raw) normals.add(n.fromBufferAttribute(normal, vertex));
+    if (cross.dot(normals) < -1e-14) valid = false;
+    for (let j = 0; j < 3; j++) {
+      const a = vertices[j], b = vertices[(j + 1) % 3], key = `${Math.min(a, b)}:${Math.max(a, b)}`;
+      const count = edges.get(key) ?? { count: 0, direction: 0 };
+      count.count++; count.direction += a < b ? 1 : -1; edges.set(key, count);
+      parent[find(a)] = find(b);
+    }
+    faces.push({ vertex: vertices[0], volume: a.dot(cross.copy(b).cross(c)) / 6 });
+  }
+  const volumes = new Map<number, number>();
+  for (const face of faces) { const id = find(face.vertex); volumes.set(id, (volumes.get(id) ?? 0) + face.volume); }
+  valid &&= faces.length > 0 && [...edges.values()].every(edge => edge.count === 2 && edge.direction === 0)
+    && [...volumes.values()].every(volume => volume > 1e-12);
+  closed.set(geometry, valid);
+  return valid;
+}
+
+/** Whitelist opaque solids; thin/open/transmissive parts retain their original side. */
+export function enableOpaqueBackfaces(surface: string, geometry: THREE.BufferGeometry,
+  material: THREE.MeshPhysicalMaterial, representation: "array" | "full") {
+  const candidate = surface === "Index_Inlay" || surface === "Optical_Diffuser"
+    || representation === "array" && surface === "Ivory_Edges"
+    || representation === "full" && surface === "Titanium_Fasteners";
+  if (!candidate || material.transparent || material.transmission > 0 || material.opacity !== 1
+    || material.blending !== THREE.NormalBlending || !material.depthWrite
+    || material.side !== THREE.DoubleSide && material.side !== THREE.FrontSide
+    || !closedOutwardSurface(geometry)) return false;
+  // Three normally derives shadowSide from side. Preserve the authored shadow.
+  material.shadowSide ??= material.side === THREE.DoubleSide ? THREE.DoubleSide : THREE.BackSide;
+  if (material.side !== THREE.FrontSide) { material.side = THREE.FrontSide; material.needsUpdate = true; }
+  return true;
+}

package/ui/rhine/original/program-preparation.ts

@@ -0,0 +1,111 @@
+import * as THREE from "three";
+
+export type ProgramPreparationStatus = "pending" | "compiling" | "ready" | "unsupported" | "cancelled" | "failed";
+type PreparedProgram = { program: WebGLProgram; getUniforms(): unknown; getAttributes(): unknown };
+type Prepared = { objects: THREE.Group[]; materials: Set<THREE.Material> };
+
+/** Keep warm material references alive so Three does not release their programs. */
+export class ProgramPreparation {
+  private readonly retained: Prepared[] = [];
+  private generation = 0;
+  private disposed = false;
+  private readonly records = new Map<string, { status: ProgramPreparationStatus; materials: number; programs: number; durationMs: number; compileMs: number; reflectionMs: number }>();
+
+  stats() { return Object.fromEntries([...this.records].map(([key, value]) => [key, { ...value }])); }
+
+  async prepare(kind: string, sources: readonly THREE.Object3D[], renderer: THREE.WebGLRenderer,
+    camera: THREE.Camera, scene: THREE.Scene, colorTarget: THREE.WebGLRenderTarget) {
+    if (this.disposed) return;
+    const generation = this.generation, began = performance.now();
+    const record = { status: "compiling" as ProgramPreparationStatus, materials: 0, programs: 0, durationMs: 0, compileMs: 0, reflectionMs: 0 };
+    this.records.set(kind, record);
+    const prepared: Prepared = { objects: [new THREE.Group(), new THREE.Group()], materials: new Set() };
+    this.retained.push(prepared);
+    const copies = new Map<THREE.Material, THREE.Material[]>();
+    for (const source of sources) source.traverse(object => {
+      if (!(object instanceof THREE.Mesh || object instanceof THREE.Line || object instanceof THREE.Points || object instanceof THREE.Sprite)) return;
+      const materials = Array.isArray(object.material) ? object.material : [object.material];
+      for (const material of materials) {
+        let variants = copies.get(material);
+        if (!variants) {
+          const sides = material.transparent && material.side === THREE.DoubleSide && !material.forceSinglePass
+            ? [THREE.BackSide, THREE.FrontSide] : [material.side];
+          variants = sides.map(side => {
+            const copy = material.clone();
+            copy.onBeforeCompile = material.onBeforeCompile;
+            copy.customProgramCacheKey = material.customProgramCacheKey;
+            copy.side = side; copy.forceSinglePass = true;
+            prepared.materials.add(copy);
+            return copy;
+          });
+          copies.set(material, variants);
+        }
+        for (const material of variants) {
+          const copy = object.clone(false) as THREE.Mesh;
+          copy.material = material;
+          prepared.objects[object.layers.isEnabled(1) ? 1 : 0].add(copy);
+        }
+      }
+    });
+    record.materials = prepared.materials.size;
+    const cancelled = () => this.disposed || generation !== this.generation || renderer.getContext().isContextLost();
+    try {
+      const compiled = new Set<PreparedProgram>();
+      // Compile under the same output target as each real pass. Restore it before
+      // yielding: the visible renderer keeps running while the driver compiles.
+      for (let pass = 0; pass < prepared.objects.length; pass++) {
+        if (cancelled()) { record.status = "cancelled"; return; }
+        const target = renderer.getRenderTarget(), face = renderer.getActiveCubeFace(), mip = renderer.getActiveMipmapLevel();
+        try {
+          renderer.setRenderTarget(pass === 0 ? colorTarget : null);
+          const compileCamera = camera.clone();
+          if (pass === 1) compileCamera.layers.set(1);
+          const materials = renderer.compile(prepared.objects[pass], compileCamera, scene);
+          for (const material of materials) {
+            const program = (renderer.properties.get(material) as { currentProgram?: PreparedProgram }).currentProgram;
+            if (program) compiled.add(program);
+          }
+        } finally { renderer.setRenderTarget(target, face, mip); }
+      }
+      record.compileMs = performance.now() - began;
+      const gl = renderer.getContext();
+      const extension = renderer.extensions.get("KHR_parallel_shader_compile") as KHR_parallel_shader_compile | null;
+      if (!extension) { record.status = "unsupported"; return; }
+      // Snapshot program handles, not material.currentProgram: animation may
+      // select another variant while this task waits. Polling completion is the
+      // nonblocking KHR operation; never query LINK_STATUS or info logs early.
+      const programs = [...compiled].map(program => program.program);
+      record.programs = programs.length;
+      while (!cancelled()) {
+        if (performance.now() - began > 30000) throw new Error("Archive program preparation timed out.");
+        if (programs.every(program => gl.getProgramParameter(program, extension.COMPLETION_STATUS_KHR))) {
+          if (programs.some(program => !gl.getProgramParameter(program, gl.LINK_STATUS)))
+            throw new Error("Archive program preparation failed to link a material.");
+          // Three's first-use reflection performs synchronous info-log and
+          // uniform queries even after linking. Finish that once here, outside
+          // the visible draw, yielding between programs to bound each task.
+          for (const program of compiled) {
+            if (cancelled()) { record.status = "cancelled"; return; }
+            const start = performance.now();
+            program.getUniforms(); program.getAttributes();
+            record.reflectionMs += performance.now() - start;
+            await new Promise<void>(resolve => setTimeout(resolve, 0));
+          }
+          record.status = cancelled() ? "cancelled" : "ready"; return;
+        }
+        await new Promise<void>(resolve => setTimeout(resolve, 10));
+      }
+      record.status = "cancelled";
+    } catch (error) {
+      record.status = "failed"; throw error;
+    } finally { record.durationMs = performance.now() - began; }
+  }
+
+  invalidate() {
+    this.generation++;
+    this.records.clear();
+    for (const prepared of this.retained) for (const material of prepared.materials) material.dispose();
+    this.retained.length = 0;
+  }
+  dispose() { this.disposed = true; this.invalidate(); }
+}

package/ui/rhine/original/quality-renderer.ts

@@ -0,0 +1,97 @@
+import * as THREE from "three";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { SMAAPass } from "three/addons/postprocessing/SMAAPass.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+import { renderDimensions, type RenderQuality } from "./render-quality";
+
+export function applyTextureQuality(
+  root: THREE.Object3D,
+  renderer: THREE.WebGLRenderer,
+  quality: RenderQuality,
+) {
+  const maximum = Math.min(
+    quality.anisotropy,
+    renderer.capabilities.getMaxAnisotropy(),
+  );
+  const textures = new Set<THREE.Texture>();
+  root.traverse((object) => {
+    if (!(object instanceof THREE.Mesh)) return;
+    for (const material of Array.isArray(object.material)
+      ? object.material
+      : [object.material]) {
+      for (const value of Object.values(material)) {
+        if (value instanceof THREE.Texture && !value.isRenderTargetTexture)
+          textures.add(value);
+      }
+    }
+  });
+  for (const texture of textures) {
+    // Oblique printed text gets a small, local sampling budget; the scene's
+    // large baked textures retain the selected performance preset.
+    const requested = texture.userData.archivePrint
+      ? Math.min(16, renderer.capabilities.getMaxAnisotropy()) : maximum;
+    if (texture.anisotropy === requested) continue;
+    texture.anisotropy = requested;
+    texture.needsUpdate = true;
+  }
+}
+
+export function resizeQuality(
+  renderer: THREE.WebGLRenderer,
+  composer: EffectComposer,
+  host: HTMLElement,
+  quality: RenderQuality,
+  options: { sharpLabels?: boolean } = {},
+) {
+  const width = Math.max(1, host.clientWidth),
+    height = Math.max(1, host.clientHeight);
+  const stageScale = host.getBoundingClientRect().width / width;
+  const dimensions = renderDimensions(
+    quality,
+    width,
+    height,
+    stageScale,
+    devicePixelRatio,
+    renderer.capabilities.maxTextureSize,
+  );
+  // Only the final drawing buffer and printed labels use the finer grid.
+  // Lighting, AO, transmission, depth capture and DOF keep their existing targets.
+  const labelDimensions = options.sharpLabels ? renderDimensions(
+    { ...quality, scale: 100, pixelRatio: 2 }, width, height, stageScale, 2,
+    renderer.capabilities.maxTextureSize,
+  ) : dimensions;
+  const outputRatio = Math.max(dimensions.ratio, labelDimensions.ratio);
+  renderer.setPixelRatio(outputRatio);
+  renderer.setSize(width, height);
+  composer.setPixelRatio(dimensions.ratio);
+  composer.setSize(width, height);
+  renderer.transmissionResolutionScale = quality.transmission;
+  host.dataset.renderQuality = JSON.stringify({
+    ...dimensions,
+    outputRatio,
+    labelRatio: options.sharpLabels ? outputRatio : undefined,
+    labelWidth: options.sharpLabels ? Math.max(1, Math.floor(width * outputRatio)) : undefined,
+    labelHeight: options.sharpLabels ? Math.max(1, Math.floor(height * outputRatio)) : undefined,
+    antialias: quality.antialias,
+    transmission: quality.transmission,
+    anisotropy: Math.min(
+      quality.anisotropy,
+      renderer.capabilities.getMaxAnisotropy(),
+    ),
+  });
+  return dimensions;
+}
+
+export function createViewerPipeline(
+  renderer: THREE.WebGLRenderer,
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+) {
+  const composer = new EffectComposer(renderer);
+  const smaa = new SMAAPass();
+  composer.addPass(new RenderPass(scene, camera));
+  composer.addPass(smaa);
+  composer.addPass(new OutputPass());
+  return { composer, smaa };
+}

package/ui/rhine/original/quality-settings.ts

@@ -0,0 +1,111 @@
+import {
+  matchingPreset,
+  presetLabels,
+  type QualityPreset,
+  type RenderQuality,
+} from "./render-quality";
+
+function select(
+  quality: RenderQuality,
+  key: keyof RenderQuality,
+  label: string,
+  hint: string,
+  choices: (readonly [string | number, string])[],
+) {
+  return `<label class="quality-control"><span>${label}<small>${hint}</small></span><select data-quality="${key}" aria-label="${label}">${choices.map(([value, text]) => `<option value="${value}" ${quality[key] === value ? "selected" : ""}>${text}</option>`).join("")}</select></label>`;
+}
+function range(
+  quality: RenderQuality,
+  key: "scale" | "depthOfField",
+  label: string,
+  hint: string,
+  min: number,
+  max: number,
+) {
+  return `<label class="quality-control quality-range"><span>${label}<small>${hint}</small></span><div><input type="range" data-quality="${key}" aria-label="${label}" min="${min}" max="${max}" step="5" value="${quality[key]}"/><output data-quality-output="${key}">${quality[key]}%</output></div></label>`;
+}
+export function qualityMarkup(quality: RenderQuality) {
+  const preset = matchingPreset(quality);
+  return `<section class="quality-settings" aria-label="画质设置">
+    <div class="quality-heading"><h3>RENDER QUALITY <span>渲染画质</span></h3><select id="quality-preset" aria-label="画质预设">${(Object.keys(presetLabels) as QualityPreset[]).map((key) => `<option value="${key}" ${preset === key ? "selected" : ""}>${presetLabels[key]}</option>`).join("")}<option value="custom" disabled ${preset === "custom" ? "selected" : ""}>自定义</option></select></div>
+    <p class="quality-summary" id="quality-summary" aria-live="polite"></p>
+    <details class="quality-advanced"><summary>精细设置 <span>清晰度 / 材质 / 阴影</span></summary><div class="quality-grid">
+    ${range(quality, "scale", "渲染比例", "相对屏幕像素，受密度上限限制；高比例改善细线", 50, 200)}
+    ${select(
+      quality,
+      "pixelRatio",
+      "像素密度上限",
+      "控制高密度屏幕的原生像素倍率",
+      [1, 1.5, 2, 3].map((v) => [v, `${v}×`]),
+    )}
+    ${select(quality, "antialias", "抗锯齿", "SMAA 平滑模型边缘与后处理结果", [
+      ["off", "原始"],
+      ["smaa", "SMAA"],
+    ])}
+    ${select(
+      quality,
+      "anisotropy",
+      "纹理过滤",
+      "改善倾斜视角下的标签细节",
+      [1, 2, 4, 8, 16].map((v) => [v, `${v}×`]),
+    )}
+    ${select(
+      quality,
+      "transmission",
+      "透明材质分辨率 · 阵列",
+      "控制阵列盖板折射清晰度；档案架使用 100%",
+      [0.25, 0.5, 0.75, 1].map((v) => [v, `${v * 100}%`]),
+    )}
+    ${select(
+      quality,
+      "shadows",
+      "阴影分辨率 · 阵列",
+      "更高分辨率保留更细的投影边缘",
+      [
+        [0, "关闭"],
+        [1024, "1024"],
+        [2048, "2048"],
+        [4096, "4096"],
+      ],
+    )}
+    ${select(
+      quality,
+      "aoSamples",
+      "环境遮蔽 · 阵列",
+      "采样越多，接缝暗部越细腻",
+      [
+        [0, "关闭"],
+        [16, "16 采样"],
+        [32, "32 采样"],
+        [64, "64 采样"],
+      ],
+    )}
+    ${select(
+      quality,
+      "aoResolution",
+      "遮蔽分辨率 · 阵列",
+      "降低可减轻环境遮蔽的渲染负担",
+      [0.5, 0.75, 1].map((v) => [v, `${v * 100}%`]),
+    )}
+    ${range(quality, "depthOfField", "景深强度 · 阵列", "0% 关闭；100% 保留原始镜头虚化；档案架不虚化", 0, 150)}
+    </div></details><p class="quality-note">即时生效并自动保存。清晰度与材质设置同步至 360° 查看器。高渲染比例更适合静态观察；缓冲上限为 829 万像素，硬件限制时自动收敛。</p>
+  </section>`;
+}
+
+export function syncQualityUI(quality: RenderQuality) {
+  const preset = document.querySelector<HTMLSelectElement>("#quality-preset");
+  if (!preset) return;
+  preset.value = matchingPreset(quality);
+  document
+    .querySelectorAll<HTMLInputElement | HTMLSelectElement>("[data-quality]")
+    .forEach((control) => {
+      const key = control.dataset.quality as keyof RenderQuality;
+      control.value = String(quality[key]);
+      control.disabled = key === "aoResolution" && quality.aoSamples === 0;
+    });
+  document
+    .querySelectorAll<HTMLOutputElement>("[data-quality-output]")
+    .forEach((output) => {
+      output.value = `${quality[output.dataset.qualityOutput as keyof RenderQuality]}%`;
+    });
+}

package/ui/rhine/original/render-quality.ts

@@ -0,0 +1,163 @@
+/** Rendering controls are independent of lighting, materials and animation. */
+export type RenderQuality = {
+  scale: number;
+  pixelRatio: number;
+  antialias: "off" | "smaa";
+  shadows: number;
+  aoSamples: number;
+  aoResolution: number;
+  depthOfField: number;
+  transmission: number;
+  anisotropy: number;
+};
+
+export const qualityPresets = {
+  performance: {
+    // Keep thin cassette rims at native CSS resolution. Save work through
+    // lighting/postprocessing instead of enlarging an undersampled image.
+    scale: 100,
+    pixelRatio: 1,
+    antialias: "smaa",
+    shadows: 1024,
+    aoSamples: 0,
+    aoResolution: 0.5,
+    depthOfField: 0,
+    transmission: 0.5,
+    anisotropy: 4,
+  },
+  original: {
+    scale: 100,
+    pixelRatio: 1.5,
+    antialias: "off",
+    shadows: 2048,
+    aoSamples: 32,
+    aoResolution: 1,
+    depthOfField: 100,
+    transmission: 1,
+    anisotropy: 16,
+  },
+  high: {
+    scale: 125,
+    pixelRatio: 2,
+    antialias: "smaa",
+    shadows: 4096,
+    aoSamples: 32,
+    aoResolution: 1,
+    depthOfField: 100,
+    transmission: 1,
+    anisotropy: 16,
+  },
+  ultra: {
+    scale: 150,
+    pixelRatio: 2,
+    antialias: "smaa",
+    shadows: 4096,
+    aoSamples: 64,
+    aoResolution: 1,
+    depthOfField: 100,
+    transmission: 1,
+    anisotropy: 16,
+  },
+} as const satisfies Record<string, RenderQuality>;
+export type QualityPreset = keyof typeof qualityPresets;
+export const presetLabels: Record<QualityPreset, string> = {
+  performance: "性能",
+  original: "原始",
+  high: "高",
+  ultra: "极高",
+};
+
+const member = <T>(value: unknown, choices: readonly T[], fallback: T): T =>
+  choices.includes(value as T) ? (value as T) : fallback;
+const range = (
+  value: unknown,
+  min: number,
+  max: number,
+  step: number,
+  fallback: number,
+) =>
+  typeof value === "number" && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, Math.round(value / step) * step))
+    : fallback;
+
+export function normalizeQuality(
+  value: unknown,
+  legacyHigh = true,
+): RenderQuality {
+  const base = qualityPresets.original;
+  const v =
+    value && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+  // Older low quality retained full resolution, shadows and transmission.
+  const fallback = legacyHigh
+    ? base
+    : { ...base, pixelRatio: 1, aoSamples: 0, depthOfField: 0 };
+  return {
+    scale: range(v.scale, 50, 200, 5, fallback.scale),
+    pixelRatio: member(v.pixelRatio, [1, 1.5, 2, 3], fallback.pixelRatio),
+    antialias: member(
+      v.antialias,
+      ["off", "smaa"] as const,
+      fallback.antialias,
+    ),
+    shadows: member(v.shadows, [0, 1024, 2048, 4096], fallback.shadows),
+    aoSamples: member(v.aoSamples, [0, 16, 32, 64], fallback.aoSamples),
+    aoResolution: member(v.aoResolution, [0.5, 0.75, 1], fallback.aoResolution),
+    depthOfField: range(v.depthOfField, 0, 150, 5, fallback.depthOfField),
+    transmission: member(
+      v.transmission,
+      [0.25, 0.5, 0.75, 1],
+      fallback.transmission,
+    ),
+    anisotropy: member(v.anisotropy, [1, 2, 4, 8, 16], fallback.anisotropy),
+  };
+}
+
+/** Upgrade the old complete performance preset without changing custom values. */
+export function restoreQuality(value: unknown): RenderQuality {
+  const legacyPerformance = { ...qualityPresets.performance, scale: 80, antialias: "off" };
+  if (value && typeof value === "object" &&
+    Object.entries(legacyPerformance).every(([key, expected]) =>
+      (value as Record<string, unknown>)[key] === expected)) {
+    return { ...qualityPresets.performance };
+  }
+  return normalizeQuality(value);
+}
+
+export function matchingPreset(
+  quality: RenderQuality,
+): QualityPreset | "custom" {
+  return (
+    (Object.keys(qualityPresets) as QualityPreset[]).find((key) =>
+      Object.entries(qualityPresets[key]).every(
+        ([field, value]) => quality[field as keyof RenderQuality] === value,
+      ),
+    ) ?? "custom"
+  );
+}
+
+export function renderDimensions(
+  quality: RenderQuality,
+  width: number,
+  height: number,
+  stageScale: number,
+  deviceRatio: number,
+  maxTextureSize: number,
+) {
+  const requested =
+    (Math.min(deviceRatio, quality.pixelRatio) * stageScale * quality.scale) /
+    100;
+  // Bound all full-resolution postprocessing targets to 8.3 MP and device limits.
+  const ratio = Math.min(
+    requested,
+    Math.sqrt(8_294_400 / Math.max(1, width * height)),
+    maxTextureSize / Math.max(1, width, height),
+  );
+  return {
+    ratio,
+    width: Math.max(1, Math.floor(width * ratio)),
+    height: Math.max(1, Math.floor(height * ratio)),
+    limited: ratio < requested - 0.0001,
+  };
+}