ravensight-playtest 0.5.2 → 0.7.0

package/src/assets/inventory.js

@@ -0,0 +1,337 @@
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+import { decodePng, parseOgg, parseWav, pngHasAlphaChannel, readPngHeader } from './formats.js';
+import { guessLayout, looksLikePixelArt, measureAlpha, measurePixelPitch, ALPHA_THRESHOLD } from './measure.js';
+
+/**
+ * The inventory: what a studio's declared asset folder holds, measured, on this
+ * machine. It reads that folder and nothing else, follows no link out of it, and
+ * nothing here uploads anything. The feature and create loops show the result to
+ * the model as a manifest and put only counts and warning kinds in the report
+ * that goes to the server; the names stay here.
+ */
+
+export const DEFAULT_ASSETS_DIR = 'assets';
+export const MAX_ASSET_FILES = 2000;
+
+/** Files larger than this are named and sized but not read. */
+export const MAX_MEASURED_BYTES = 256 * 1024 * 1024;
+
+export const IMAGE_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.webp', '.svg', '.bmp', '.tga', '.exr', '.hdr']);
+export const AUDIO_EXTENSIONS = Object.freeze(['.wav', '.ogg', '.mp3']);
+/** A studio's own 3D models. Listed by type and size: nothing here reads inside one. */
+export const MODEL_EXTENSIONS = Object.freeze(['.glb', '.gltf', '.obj', '.fbx', '.dae', '.blend']);
+/** Art or audio by extension: binary, or in SVG's case drawn. Never model input. */
+export const MEDIA_EXTENSIONS = Object.freeze([...IMAGE_EXTENSIONS, ...AUDIO_EXTENSIONS, ...MODEL_EXTENSIONS]);
+
+/** Sidecars Godot writes beside a file, which are not assets of their own. */
+const IGNORED_SUFFIXES = Object.freeze(['.import', '.uid', '.tmp']);
+
+const FAINT_BOX_RATIO = 1.1;
+const SEAM_LIMIT = 0.2;
+
+/**
+ * Each kind of warning, in plain words. `summary` is the only text about a warning
+ * that ever leaves this machine, which is why it names no file and no number.
+ */
+export const WARNING_KINDS = Object.freeze({
+  upscaled: 'The art is upscaled: one art pixel covers several file pixels, so its real grid is smaller than the file and may not be the grid it was meant to have.',
+  grid_mismatch: 'The real pixel grid differs from the grid you said to expect.',
+  uneven_pitch: 'The measured pixel size does not divide the image evenly, so a nearest neighbour resize will not come out clean.',
+  faint_alpha: 'Nearly invisible pixels reach far past what you can see, so threshold alpha before trimming, or a trim keeps most of the canvas.',
+  tile_frame: 'A tile has its own frame drawn around its edge, which draws a grid across anything laid from it.',
+  tile_seam: 'Opposite edges of a tile do not match, so a seam shows when it repeats.',
+  codec: 'An audio file is in a form Godot does not import as sound.',
+  damaged: 'A file is damaged or cut short.',
+  empty_image: 'An image is fully transparent, so it draws nothing.',
+  not_measured: 'A file was listed by type and size only, because this inventory does not read inside that format or the file is very large.',
+  linear_filter: 'The project draws textures with a smooth filter by default, so pixel art blurs unless the node drawing it sets the nearest filter.'
+});
+
+function warning(kind, text) {
+  return { kind, text };
+}
+
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * Where the declared folder is, or why it cannot be used. It has to be inside the
+ * project, by real path, so a link cannot lead the inventory out.
+ *
+ * @param {{projectDir: string, folder?: string}} input
+ * @returns {Promise<{ok: true, absolute: string, relative: string, exists: boolean}|{ok: false, reason: string}>}
+ */
+export async function resolveAssetsDir({ projectDir, folder = DEFAULT_ASSETS_DIR }) {
+  const root = await realpath(projectDir);
+  const absolute = path.resolve(root, folder);
+  const inside = target => target === root || target.startsWith(`${root}${path.sep}`);
+  if (!inside(absolute)) return { ok: false, reason: `The assets folder has to be inside the project, and ${folder} is not.` };
+  let real;
+  try {
+    real = await realpath(absolute);
+  } catch {
+    return { ok: true, absolute, relative: path.relative(root, absolute).split(path.sep).join('/'), exists: false };
+  }
+  if (!inside(real)) return { ok: false, reason: `The assets folder has to be inside the project, and ${folder} links out of it.` };
+  const info = await lstat(real);
+  if (!info.isDirectory()) return { ok: false, reason: `${folder} is not a folder.` };
+  return { ok: true, absolute: real, relative: path.relative(root, real).split(path.sep).join('/'), exists: true };
+}
+
+/** The files in a folder. Links are skipped, not followed, and so are hidden names. */
+async function walk(directory, out, limit) {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+  for (const entry of entries) {
+    if (out.files.length >= limit) { out.truncated = true; return; }
+    if (entry.name.startsWith('.') || entry.isSymbolicLink()) continue;
+    const absolute = path.join(directory, entry.name);
+    if (entry.isDirectory()) await walk(absolute, out, limit);
+    else if (entry.isFile() && !IGNORED_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) out.files.push(absolute);
+  }
+}
+
+/** Measure one PNG, with the warnings its pixels earn. */
+function measurePng(data, relativePath, grid) {
+  const header = readPngHeader(data);
+  if (!header) return { image: null, warnings: [warning('damaged', 'The name says PNG, but this is not a PNG file.')] };
+  const image = { width: header.width, height: header.height, has_alpha_channel: pngHasAlphaChannel(header), bit_depth: header.bitDepth };
+  const warnings = [];
+  if (header.problem) {
+    warnings.push(warning('damaged', `This PNG is damaged: ${header.problem}.`));
+    return { image, warnings };
+  }
+  const decoded = decodePng(header);
+  if (decoded === null) {
+    warnings.push(warning('not_measured', header.interlaced
+      ? 'This PNG is interlaced, so only its size was read, not its pixels.'
+      : 'This PNG is too large to decode, so only its size was read, not its pixels.'));
+    return { image, warnings };
+  }
+  if (decoded.problem) {
+    warnings.push(warning('damaged', `This PNG is damaged: ${decoded.problem}.`));
+    return { image, warnings };
+  }
+  const alpha = measureAlpha(decoded);
+  const pitch = measurePixelPitch(decoded);
+  const layout = guessLayout(decoded, alpha, relativePath);
+  Object.assign(image, { alpha, pixel_pitch: pitch, layout, pixel_art: looksLikePixelArt(decoded, alpha, pitch, layout) });
+
+  if (pitch.value > 1) {
+    warnings.push(warning('upscaled', `One art pixel is ${pitch.exact ? '' : 'about '}${pitch.value} file pixels, so this ${image.width} by ${image.height} file is ${pitch.exact ? '' : 'about '}${pitch.art_width} by ${pitch.art_height} art pixels. Trust that number, not the grid the art was meant to have.`));
+    if (!pitch.exact || image.width % pitch.value !== 0 || image.height % pitch.value !== 0) {
+      warnings.push(warning('uneven_pitch', `The cells do not fit a whole-number grid. Resizing with the nearest filter will drop or double rows, so resize by the most common colour under each target pixel, or redraw at the size you need.`));
+    }
+  }
+  if (grid && pitch.art_width !== grid && pitch.art_height !== grid) {
+    warnings.push(warning('grid_mismatch', `You expected a ${grid} grid, and this measures ${pitch.art_width} by ${pitch.art_height} art pixels.`));
+  }
+  const { box_any: any, box_threshold: seen } = alpha;
+  if (!any) warnings.push(warning('empty_image', 'This image is fully transparent, so it draws nothing.'));
+  if (any && seen && any.width * any.height >= seen.width * seen.height * FAINT_BOX_RATIO) {
+    warnings.push(warning('faint_alpha', `Nearly invisible pixels reach far past what you can see. A trim that keeps every pixel that is not fully transparent keeps ${any.width} by ${any.height}; a trim at half alpha (${ALPHA_THRESHOLD} of 255) keeps ${seen.width} by ${seen.height}. Threshold alpha before trimming.`));
+  }
+  if (layout.framed) {
+    warnings.push(warning('tile_frame', `${layout.kind === 'sheet' ? 'Each tile here has' : 'This tile has'} its own frame drawn around its edge. Side by side, the frames draw a grid across the floor or wall. Use tiles with no per-tile frame, or one seamless texture.`));
+  }
+  if (layout.seam !== null && layout.seam > SEAM_LIMIT) {
+    warnings.push(warning('tile_seam', `Opposite edges differ by ${Math.round(layout.seam * 100)} percent, so a seam shows when this tile repeats.`));
+  }
+  return { image, warnings };
+}
+
+/** Measure one WAV or Ogg. */
+function measureAudio(data, extension) {
+  const parsed = extension === '.wav' ? parseWav(data) : parseOgg(data);
+  if (!parsed) return { audio: null, warnings: [warning('damaged', `The name says ${extension.slice(1).toUpperCase()}, but the file is not one.`)] };
+  const audio = {
+    format: extension.slice(1),
+    codec: parsed.codec,
+    channels: parsed.channels,
+    sample_rate: parsed.sampleRate,
+    ...(parsed.bitsPerSample ? { bits_per_sample: parsed.bitsPerSample } : {}),
+    duration_seconds: parsed.durationSeconds === null ? null : Math.round(parsed.durationSeconds * 1000) / 1000
+  };
+  const warnings = [];
+  if (parsed.problem) warnings.push(warning('damaged', `This audio file is damaged: ${parsed.problem}.`));
+  if (extension === '.ogg' && parsed.codec === 'opus') warnings.push(warning('codec', 'This Ogg holds Opus, and Godot imports only Vorbis from an Ogg file. Convert it to Ogg Vorbis or WAV.'));
+  if (extension === '.wav' && !['pcm', 'float'].includes(parsed.codec)) warnings.push(warning('codec', `This WAV is ${parsed.codec}, and Godot imports uncompressed WAV. Convert it to plain PCM.`));
+  else if (extension === '.wav' && parsed.extensible) warnings.push(warning('codec', 'This WAV uses the extended WAV header, which Godot refuses to import. Save it again as plain PCM.'));
+  return { audio, warnings };
+}
+
+/**
+ * The project's default canvas texture filter, from project.godot. Godot's own
+ * default is linear when the setting is absent.
+ *
+ * @param {string} text
+ * @returns {'nearest'|'other'}
+ */
+export function defaultFilter(text) {
+  let section = '';
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith('[')) section = line;
+    else if (section === '[rendering]') {
+      const match = /^textures\/canvas_textures\/default_texture_filter\s*=\s*(\d+)/.exec(line);
+      if (match) return match[1] === '0' ? 'nearest' : 'other';
+    }
+  }
+  return 'other';
+}
+
+/**
+ * The inventory of a project's declared folder.
+ *
+ * @param {{projectDir: string, folder?: string, grid?: number|null}} input
+ * @returns {Promise<{ok: true, folder: string, exists: boolean, files: Array<Object>, counts: Object, warnings: Array<Object>, truncated: boolean, default_filter: string}|{ok: false, reason: string}>}
+ */
+export async function buildInventory({ projectDir, folder = DEFAULT_ASSETS_DIR, grid = null }) {
+  const resolved = await resolveAssetsDir({ projectDir, folder });
+  if (!resolved.ok) return resolved;
+  const root = await realpath(projectDir);
+  const found = { files: [], truncated: false };
+  if (resolved.exists) await walk(resolved.absolute, found, MAX_ASSET_FILES);
+
+  const files = [];
+  for (const absolute of found.files) {
+    const relative = path.relative(root, absolute).split(path.sep).join('/');
+    const extension = path.extname(absolute).toLowerCase();
+    const info = await lstat(absolute);
+    const row = {
+      path: relative,
+      res_path: `res://${relative}`,
+      kind: IMAGE_EXTENSIONS.includes(extension) ? 'image' : (AUDIO_EXTENSIONS.includes(extension) ? 'audio' : (MODEL_EXTENSIONS.includes(extension) ? 'model' : 'other')),
+      format: extension.slice(1) || 'none',
+      bytes: info.size,
+      warnings: []
+    };
+    const measurable = extension === '.png' || extension === '.wav' || extension === '.ogg';
+    if (measurable && info.size <= MAX_MEASURED_BYTES) {
+      const data = await readFile(absolute);
+      if (extension === '.png') {
+        const { image, warnings } = measurePng(data, relative, grid);
+        if (image) row.image = image;
+        row.warnings.push(...warnings);
+      } else {
+        const { audio, warnings } = measureAudio(data, extension);
+        if (audio) row.audio = audio;
+        row.warnings.push(...warnings);
+      }
+    } else if (row.kind !== 'other') {
+      row.warnings.push(warning('not_measured', measurable ? 'This file is too large to read, so it is listed by type and size only.' : `This inventory reads inside PNG, WAV and Ogg, so this ${row.format} file is listed by type and size only.`));
+    }
+    files.push(row);
+  }
+
+  const settings = await readFile(path.join(root, 'project.godot'), 'utf8').catch(() => '');
+  const filter = defaultFilter(settings);
+  const warnings = [];
+  if (filter !== 'nearest' && files.some(file => file.image && file.image.pixel_art)) {
+    warnings.push(warning('linear_filter', 'The project draws textures with a smooth filter by default, so pixel art blurs unless the node drawing it sets texture_filter to nearest. Set it on each node, or change the project default yourself.'));
+  }
+  return {
+    ok: true,
+    folder: resolved.relative,
+    exists: resolved.exists,
+    files,
+    counts: countOf(files),
+    warnings,
+    truncated: found.truncated,
+    default_filter: filter
+  };
+}
+
+function countOf(files) {
+  const models = files.filter(file => file.kind === 'model').length;
+  return {
+    files: files.length,
+    images: files.filter(file => file.kind === 'image').length,
+    audio: files.filter(file => file.kind === 'audio').length,
+    ...(models > 0 ? { models } : {}),
+    other: files.filter(file => file.kind === 'other').length
+  };
+}
+
+/**
+ * Every warning by kind, with how many it covers, and no name of any file: the
+ * only form a warning takes off this machine.
+ *
+ * @param {Object} inventory
+ * @returns {Array<{kind: string, count: number, summary: string}>}
+ */
+export function warningKinds(inventory) {
+  const counts = new Map();
+  const add = kind => counts.set(kind, (counts.get(kind) || 0) + 1);
+  for (const file of inventory.files) for (const item of file.warnings) add(item.kind);
+  for (const item of inventory.warnings) add(item.kind);
+  return [...counts].map(([kind, count]) => ({ kind, count, summary: WARNING_KINDS[kind] }));
+}
+
+/**
+ * The manifest the model reads: one JSON line per file, so `read_file` can page
+ * it, with no file content in it at all.
+ *
+ * @param {Object} inventory
+ * @param {string} [projectInRepository] where the project sits, when it is not the repository root
+ * @returns {string}
+ */
+export function manifestText(inventory, projectInRepository = '') {
+  const head = {
+    about: 'The art and audio this project has. Use these by res_path. Nothing else exists.',
+    ...(projectInRepository ? { project_folder_in_repository: projectInRepository } : {}),
+    folder: inventory.folder,
+    counts: inventory.counts,
+    project_default_texture_filter: inventory.default_filter === 'nearest' ? 'nearest' : 'smooth',
+    project_warnings: inventory.warnings.map(item => item.text),
+    ...(inventory.truncated ? { truncated: `only the first ${MAX_ASSET_FILES} files are listed` } : {})
+  };
+  const rows = inventory.files.map(file => {
+    const { warnings, ...rest } = file;
+    return JSON.stringify({ ...rest, ...(warnings.length ? { warnings: warnings.map(item => item.text) } : {}) });
+  });
+  return `${[JSON.stringify(head), ...rows].join('\n')}\n`;
+}
+
+/** Bytes, kept short for a terminal. */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 102.4) / 10} KB`;
+  return `${Math.round(bytes / 104857.6) / 10} MB`;
+}
+
+/** What one row of the inventory says, in a phrase. */
+export function describeFile(file) {
+  const parts = [];
+  if (file.image) {
+    const { image } = file;
+    parts.push(`${image.width}x${image.height}`);
+    if (image.alpha) {
+      parts.push(image.alpha.opaque_share === 1 ? 'no transparency' : 'transparency');
+      parts.push(image.pixel_pitch.value > 1 ? `pixel pitch ${image.pixel_pitch.exact ? '' : 'about '}${image.pixel_pitch.value}, ${image.pixel_pitch.art_width}x${image.pixel_pitch.art_height} art pixels` : 'pixel pitch 1');
+      const { layout } = image;
+      parts.push(layout.kind === 'sheet' || layout.kind === 'strip' ? `${layout.kind} ${layout.columns}x${layout.rows} of ${layout.cell_width}x${layout.cell_height}` : layout.kind);
+    }
+  }
+  if (file.audio) {
+    const { audio } = file;
+    parts.push(`${audio.codec}, ${audio.channels === 1 ? 'mono' : (audio.channels === 2 ? 'stereo' : `${audio.channels} channels`)}, ${audio.sample_rate} Hz`);
+    if (audio.duration_seconds !== null) parts.push(`${audio.duration_seconds} s`);
+  }
+  return parts.join(', ');
+}
+
+/** A sentence for the top of a listing. */
+export function countsLine(counts) {
+  return `${plural(counts.files, 'file')}: ${plural(counts.images, 'image')}, ${counts.audio} audio, ${counts.models ? `${plural(counts.models, 'model')}, ` : ''}${counts.other} other`;
+}
+
+/** Whether a path names art or audio, by extension. */
+export function isMediaPath(file) {
+  return MEDIA_EXTENSIONS.includes(path.extname(String(file)).toLowerCase());
+}
+
+export default { buildInventory, manifestText, warningKinds, resolveAssetsDir, DEFAULT_ASSETS_DIR };