875 lines
33 KiB
JavaScript
875 lines
33 KiB
JavaScript
// Node 里用 require，插件页面里用 <script> 标签挂到 window。
|
||
// service 插件页面的 require 不以插件目录为基准，所以页面里必须走 <script>。
|
||
(function () {
|
||
/**
|
||
* SpineViewer - 工具模块
|
||
* 该模块为纯 Node.js CommonJS，供 viewer/thumbnail 复用。
|
||
* 职责：
|
||
* - 识别 Spine 导出文件的类型（skel/skel.bytes/json/atlas/atlas.txt/png/jpg/jpeg/webp）
|
||
* - 在同一个目录内自动关联配套的骨骼文件、atlas、贴图
|
||
* - 从骨骼数据中检测 Spine 版本
|
||
* - 根据版本选择合适的本地运行时
|
||
*/
|
||
|
||
const fs = require('fs');
|
||
const path = require('path');
|
||
|
||
const SKELETON_EXTS = ['.skel', '.skel.bytes', '.json'];
|
||
const ATLAS_EXTS = ['.atlas', '.atlas.txt'];
|
||
const TEXTURE_EXTS = ['.png', '.jpg', '.jpeg', '.webp'];
|
||
const ALL_EXTS = SKELETON_EXTS.concat(ATLAS_EXTS, TEXTURE_EXTS);
|
||
const fileIndexCache = new Map();
|
||
const skeletonJsonCache = new Map();
|
||
const JSON_PROBE_BYTES = 256 * 1024;
|
||
|
||
// Spine 导出常见的尾缀，匹配时归一化掉（支持 - 与 _ 两种分隔符）
|
||
// 例：hero-mesh.skel / hero-data.json / hero-pma.atlas 都归一为 hero
|
||
const DEFAULT_SUFFIXES = ['pro', 'ess', 'pma', 'base', 'atlas', 'data', 'mesh'];
|
||
// 用户可在查看器里添加自己的尾缀；为避免正则注入，只允许字母、数字、- 与 _，
|
||
// 且必须以字母或数字开头。SUFFIX_MAX_LENGTH 必须与下面的正则保持一致（有测试守着）。
|
||
const SUFFIX_MAX_LENGTH = 50;
|
||
const SUFFIX_NAME_RE = /^[a-z0-9](?:[a-z0-9_-]{0,49})$/i;
|
||
let activeSuffixes = DEFAULT_SUFFIXES.slice();
|
||
let suffixRe = buildSuffixRe(activeSuffixes);
|
||
|
||
function escapeRegExp(text) {
|
||
return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||
}
|
||
|
||
function buildSuffixRe(list) {
|
||
if (!list || list.length === 0) return null;
|
||
return new RegExp('[-_](' + list.map(escapeRegExp).join('|') + ')$', 'i');
|
||
}
|
||
|
||
/** 校验并归一化单个尾缀名（去掉前导分隔符并转小写）；非法返回 null */
|
||
function normalizeSuffixName(raw) {
|
||
const name = String(raw == null ? '' : raw).trim().replace(/^[-_]+/, '');
|
||
return SUFFIX_NAME_RE.test(name) ? name.toLowerCase() : null;
|
||
}
|
||
|
||
/**
|
||
* 设置用户自定义尾缀（内置尾缀始终生效），返回当前生效的完整列表。
|
||
* 非法或重复的名字会被安静地忽略，不信任磁盘上的内容。
|
||
*/
|
||
function setSuffixes(list) {
|
||
const custom = [];
|
||
for (const raw of Array.isArray(list) ? list : []) {
|
||
const name = normalizeSuffixName(raw);
|
||
if (!name || DEFAULT_SUFFIXES.indexOf(name) !== -1) continue;
|
||
if (custom.indexOf(name) === -1) custom.push(name);
|
||
}
|
||
activeSuffixes = DEFAULT_SUFFIXES.concat(custom);
|
||
suffixRe = buildSuffixRe(activeSuffixes);
|
||
return getSuffixes();
|
||
}
|
||
|
||
/** 当前生效的尾缀（内置 + 自定义） */
|
||
function getSuffixes() {
|
||
return activeSuffixes.slice();
|
||
}
|
||
|
||
/** 仅用户自定义（非内置）的尾缀，用于持久化 */
|
||
function getCustomSuffixes() {
|
||
return activeSuffixes.filter((name) => DEFAULT_SUFFIXES.indexOf(name) === -1);
|
||
}
|
||
|
||
function unsafeAtlasPath(name, reason) {
|
||
const error = new Error('Atlas 贴图路径不安全：' + JSON.stringify(String(name)) + '（' + reason + '）');
|
||
error.code = 'UNSAFE_ATLAS_PATH';
|
||
return error;
|
||
}
|
||
|
||
/**
|
||
* Atlas 页面名来自不可信文本。先用同时覆盖 POSIX/Windows 的规则验证，
|
||
* 再交给本机 path API，避免在 macOS 上漏掉 C:\\、UNC 或反斜杠形式的越界路径。
|
||
*/
|
||
function validateAtlasPageName(name) {
|
||
const raw = String(name == null ? '' : name).trim();
|
||
if (!raw) throw unsafeAtlasPath(name, '路径为空');
|
||
if (/[\0-\x1f\x7f]/.test(raw)) throw unsafeAtlasPath(raw, '包含控制字符');
|
||
const portable = raw.replace(/\\/g, '/');
|
||
if (path.posix.isAbsolute(portable) || path.win32.isAbsolute(raw) || path.win32.isAbsolute(portable)) {
|
||
throw unsafeAtlasPath(raw, '不允许绝对路径');
|
||
}
|
||
if (portable.includes(':')) throw unsafeAtlasPath(raw, '不允许盘符、URI 或替代数据流');
|
||
const parts = portable.split('/');
|
||
if (parts.some((part) => part === '..')) throw unsafeAtlasPath(raw, '不允许 .. 路径段');
|
||
const normalized = path.posix.normalize(portable);
|
||
if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) {
|
||
throw unsafeAtlasPath(raw, '路径无效');
|
||
}
|
||
if (!TEXTURE_EXTS.includes(path.posix.extname(normalized).toLowerCase())) {
|
||
throw unsafeAtlasPath(raw, '不是支持的贴图格式');
|
||
}
|
||
return normalized.replace(/^\.\//, '');
|
||
}
|
||
|
||
function isPathInside(basePath, targetPath) {
|
||
const relative = path.relative(basePath, targetPath);
|
||
return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
|
||
}
|
||
|
||
function realpath(filePath) {
|
||
const implementation = fs.realpathSync.native || fs.realpathSync;
|
||
return implementation(filePath);
|
||
}
|
||
|
||
/**
|
||
* 解析已存在的普通文件，并同时检查词法路径和 realpath 边界。
|
||
* realpath 检查会阻止目录内的符号链接跳到允许目录之外。
|
||
*/
|
||
function resolveFileWithin(baseDir, relativeName, atlasPage) {
|
||
const safeName = atlasPage ? validateAtlasPageName(relativeName) : String(relativeName);
|
||
const base = path.resolve(baseDir);
|
||
const candidate = path.resolve(base, ...safeName.replace(/\\/g, '/').split('/'));
|
||
if (!isPathInside(base, candidate)) {
|
||
if (atlasPage) throw unsafeAtlasPath(relativeName, '路径越出允许目录');
|
||
return null;
|
||
}
|
||
if (!fs.existsSync(candidate)) return null;
|
||
let realBase;
|
||
let realCandidate;
|
||
try {
|
||
realBase = realpath(base);
|
||
realCandidate = realpath(candidate);
|
||
} catch (e) {
|
||
return null;
|
||
}
|
||
if (!isPathInside(realBase, realCandidate)) {
|
||
if (atlasPage) throw unsafeAtlasPath(relativeName, '符号链接越出允许目录');
|
||
return null;
|
||
}
|
||
try { if (!fs.statSync(realCandidate).isFile()) return null; } catch (e) { return null; }
|
||
return candidate;
|
||
}
|
||
|
||
function resolveAtlasTextureFile(atlasDir, pageName) {
|
||
return resolveFileWithin(atlasDir, pageName, true);
|
||
}
|
||
|
||
function extOf(name) {
|
||
const lower = name.toLowerCase();
|
||
for (let i = 0; i < SKELETON_EXTS.length; i++) {
|
||
if (lower.endsWith(SKELETON_EXTS[i])) return SKELETON_EXTS[i];
|
||
}
|
||
for (let i = 0; i < ATLAS_EXTS.length; i++) {
|
||
if (lower.endsWith(ATLAS_EXTS[i])) return ATLAS_EXTS[i];
|
||
}
|
||
for (let i = 0; i < TEXTURE_EXTS.length; i++) {
|
||
if (lower.endsWith(TEXTURE_EXTS[i])) return TEXTURE_EXTS[i];
|
||
}
|
||
return null;
|
||
}
|
||
|
||
function isSkeletonFile(name) {
|
||
const ext = extOf(name);
|
||
return ext === '.skel' || ext === '.skel.bytes' || ext === '.json';
|
||
}
|
||
|
||
function isAtlasFile(name) {
|
||
const ext = extOf(name);
|
||
return ext === '.atlas' || ext === '.atlas.txt';
|
||
}
|
||
|
||
function isTextureFile(name) {
|
||
const ext = extOf(name);
|
||
return TEXTURE_EXTS.indexOf(ext) !== -1;
|
||
}
|
||
|
||
/** 去掉文件名中的扩展名 */
|
||
function stemOf(name) {
|
||
const ext = extOf(name);
|
||
if (!ext) return name;
|
||
return name.slice(0, name.length - ext.length);
|
||
}
|
||
|
||
/** 归一化 stem，去掉内置与用户自定义的尾缀，用于跨文件匹配 */
|
||
function normalizeStem(name) {
|
||
const lower = stemOf(name).toLowerCase();
|
||
return suffixRe ? lower.replace(suffixRe, '') : lower;
|
||
}
|
||
|
||
// 复合后缀：Eagle 按「最后一个点」拆 name / ext，于是 EmoticonSpine.atlas.txt 变成
|
||
// name=EmoticonSpine.atlas + ext=txt。而 Eagle 的卡片把 ext === 'txt' 写死成文本预览，
|
||
// 会整个盖掉自定义缩略图。把整段复合后缀塞进 ext（name=EmoticonSpine + ext=atlas.txt），
|
||
// Eagle 认不出这个类型，就会退回「用自定义缩略图当封面」，而 name + '.' + ext 拼出来
|
||
// 仍是磁盘上的真实文件名，显示和路径都不变。
|
||
const COMPOUND_SUFFIXES = ['.skel.bytes', '.atlas.txt'];
|
||
|
||
/** 返回 { name, ext }；不是复合后缀（或没有主干名）时返回 null。 */
|
||
function splitCompoundName(fileName) {
|
||
const lower = String(fileName || '').toLowerCase();
|
||
const suffix = COMPOUND_SUFFIXES.find((s) => lower.endsWith(s));
|
||
if (!suffix) return null;
|
||
const name = String(fileName).slice(0, fileName.length - suffix.length);
|
||
if (!name) return null;
|
||
return { name, ext: suffix.slice(1) };
|
||
}
|
||
|
||
/** 从 JSON 文本中读取 spine 版本 */
|
||
function detectVersionFromJson(text) {
|
||
try {
|
||
const json = JSON.parse(text);
|
||
if (json && json.skeleton && json.skeleton.spine) {
|
||
return String(json.skeleton.spine);
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
return null;
|
||
}
|
||
|
||
/** 从二进制数据中读取 spine 版本（扫描前若干字节中的版本号） */
|
||
function detectVersionFromBuffer(buf) {
|
||
let s = '';
|
||
const bytes = new Uint8Array(buf);
|
||
const len = Math.min(bytes.length, 160);
|
||
for (let i = 0; i < len; i++) {
|
||
s += String.fromCharCode(bytes[i]);
|
||
}
|
||
const m = s.match(/(\d+\.\d+(?:\.\d+)?)/);
|
||
return m ? m[1] : null;
|
||
}
|
||
|
||
/** 从文件读取 spine 版本 */
|
||
function detectVersion(filePath) {
|
||
const lower = filePath.toLowerCase();
|
||
if (lower.endsWith('.json')) {
|
||
return detectVersionFromJson(fs.readFileSync(filePath, 'utf8'));
|
||
}
|
||
return detectVersionFromBuffer(fs.readFileSync(filePath));
|
||
}
|
||
|
||
/**
|
||
* 根据检测到的版本与文件类型，选择本地运行时目录。
|
||
* - 3.4–3.7 二进制通过本地兼容解析器加载，始终使用对应版本运行时
|
||
*/
|
||
function chooseRuntimeDir(version, isBinary) {
|
||
if (!version) return null;
|
||
const major = parseInt(version.split('.')[0], 10);
|
||
if (major === 3) {
|
||
const minor = parseFloat(version);
|
||
if (minor === 3.4) return '3.4';
|
||
if (minor === 3.5) return '3.5';
|
||
if (minor <= 3.6) return '3.6';
|
||
if (minor <= 3.7 + 0.0001) return '3.7';
|
||
return '3.8';
|
||
} else if (major === 4) {
|
||
const minor = parseFloat(version);
|
||
if (minor <= 4.0 + 0.0001) return '4.0';
|
||
if (minor <= 4.1 + 0.0001) return '4.1';
|
||
if (minor <= 4.2 + 0.0001) return '4.2';
|
||
return '4.3';
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* 快速区分 Spine JSON、普通 JSON 和仍在写入的 JSON。
|
||
* 仅以 Spine 官方导出的 `skeleton.spine` 版本字段作为肯定标识；bones/slots 等
|
||
* 通用字段不能证明文件来自 Spine。大文件只探测前 256KB。
|
||
*/
|
||
function classifySkeletonJson(filePath) {
|
||
try {
|
||
const stat = fs.statSync(filePath);
|
||
if (!stat.isFile() || stat.size === 0) return 'pending';
|
||
const signature = stat.size + ':' + Math.round(stat.mtimeMs);
|
||
const cached = skeletonJsonCache.get(filePath);
|
||
if (cached && cached.signature === signature) return cached.kind;
|
||
|
||
const length = Math.min(stat.size, JSON_PROBE_BYTES);
|
||
const fd = fs.openSync(filePath, 'r');
|
||
const buffer = Buffer.allocUnsafe(length);
|
||
try { fs.readSync(fd, buffer, 0, length, 0); } finally { fs.closeSync(fd); }
|
||
const text = buffer.toString('utf8');
|
||
const hasSkeletonKey = /"skeleton"\s*:/i.test(text);
|
||
const versionMatch = text.match(/"skeleton"\s*:\s*\{[\s\S]{0,8192}?"spine"\s*:\s*"(\d+\.\d+(?:\.\d+)?(?:[^"\\]|\\.)*)"/i);
|
||
let kind;
|
||
if (versionMatch) {
|
||
kind = 'spine';
|
||
} else if (stat.size > JSON_PROBE_BYTES) {
|
||
kind = 'other';
|
||
} else {
|
||
try {
|
||
JSON.parse(text);
|
||
kind = 'other';
|
||
} catch (e) {
|
||
// 只有已经出现 skeleton 键但文件尚未完整写入时才继续短暂等待。
|
||
// JSONC、配置文件或损坏的普通 JSON 不应进入 Spine 补刷流程。
|
||
kind = hasSkeletonKey ? 'pending' : 'other';
|
||
}
|
||
}
|
||
|
||
if (skeletonJsonCache.size > 2048) skeletonJsonCache.clear();
|
||
skeletonJsonCache.set(filePath, { signature, kind });
|
||
return kind;
|
||
} catch (e) {
|
||
return 'pending';
|
||
}
|
||
}
|
||
|
||
function looksLikeSkeletonJson(filePath) {
|
||
return classifySkeletonJson(filePath) === 'spine';
|
||
}
|
||
|
||
/** 文件修改时间（毫秒） */
|
||
function mtimeOf(fp) {
|
||
try { return fs.statSync(fp).mtimeMs; } catch (e) { return 0; }
|
||
}
|
||
|
||
/** 读取某 item 元数据里的创建时间 btime（毫秒），用于按“同一批导入”配对 */
|
||
function btimeOf(fp) {
|
||
const d = itemMeta(path.dirname(fp));
|
||
return (d && d.btime) || 0;
|
||
}
|
||
|
||
/**
|
||
* Eagle item 的实际入库时间。
|
||
* metadata.json 的 birthtime 在生成缩略图、修改标签后也不会改变，比素材自身的
|
||
* btime/mtime 更适合判断多个独立 .info 项是否来自同一次拖入。
|
||
*/
|
||
function importTimeOf(fp) {
|
||
try {
|
||
const metaPath = path.join(path.dirname(fp), 'metadata.json');
|
||
const stat = fs.statSync(metaPath);
|
||
return stat.birthtimeMs || stat.ctimeMs || stat.mtimeMs || 0;
|
||
} catch (e) {
|
||
return btimeOf(fp);
|
||
}
|
||
}
|
||
|
||
/** 骨骼版本所属家族（3x / 4x），atlas 格式按版本家族区分 */
|
||
function versionFamily(version) {
|
||
if (!version) return null;
|
||
const major = parseInt(version.split('.')[0], 10);
|
||
return major <= 3 ? '3x' : '4x';
|
||
}
|
||
|
||
/** 根据 atlas 文本判断其格式家族（3x / 4x） */
|
||
function atlasFamily(atlasText) {
|
||
if (!atlasText) return null;
|
||
// 4.x atlas 用 `bounds:` 定义区域；3.x 用 `xy:`/`size:`/`orig:`/`offset:`。
|
||
// 注意：`scale:` 在 3.x 也会出现（如字体缩放），不能单独作为 4x 依据。
|
||
// 因此以 `bounds:` 作为最可靠的 4.x 标志；若整体含 `xy:` 判定为 3x。
|
||
if (/\bbounds\s*:/.test(atlasText)) return '4x';
|
||
if (/\bxy\s*:/.test(atlasText)) return '3x';
|
||
return '3x';
|
||
}
|
||
|
||
/** 读取某 item 文件夹的 metadata.json（含 folders、isDeleted、btime 等） */
|
||
function itemMeta(itemDir) {
|
||
if (!itemDir) return null;
|
||
try {
|
||
return JSON.parse(fs.readFileSync(path.join(itemDir, 'metadata.json'), 'utf8'));
|
||
} catch (e) {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/** 读取某个资产文件所属 item 文件夹的 Eagle 逻辑文件夹 id 列表 */
|
||
function foldersOfItem(filePath) {
|
||
const d = itemMeta(path.dirname(filePath));
|
||
return d && Array.isArray(d.folders) ? d.folders : [];
|
||
}
|
||
|
||
/** 判断某 item 是否已被放入 Eagle 回收站（isDeleted） */
|
||
function isItemDeleted(filePath) {
|
||
const d = itemMeta(path.dirname(filePath));
|
||
return !!(d && d.isDeleted);
|
||
}
|
||
|
||
/** 从任意 item 路径向上定位 Eagle 库根目录 */
|
||
function findLibraryRoot(filePath) {
|
||
let dir = path.dirname(filePath); // item 文件夹
|
||
for (let i = 0; i < 8; i++) {
|
||
const parent = path.dirname(dir);
|
||
if (parent === dir) break;
|
||
try {
|
||
if (fs.existsSync(path.join(parent, 'metadata.json')) && fs.existsSync(path.join(parent, 'images'))) {
|
||
return parent;
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
dir = parent;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/** 解析库根 metadata.json，返回 { folderId -> children[] } 及文件夹名 */
|
||
function readFolderInfo(libRoot) {
|
||
const map = {};
|
||
const names = {};
|
||
if (!libRoot) return { map, names };
|
||
try {
|
||
const d = JSON.parse(fs.readFileSync(path.join(libRoot, 'metadata.json'), 'utf8'));
|
||
const folders = d.folders || [];
|
||
for (const f of folders) {
|
||
if (!f) continue;
|
||
map[f.id] = Array.isArray(f.children) ? f.children : [];
|
||
names[f.id] = f.name || '';
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
return { map, names };
|
||
}
|
||
|
||
/**
|
||
* 计算允许匹配的 Eagle 文件夹 id 集合：
|
||
* 仅包含「选中文件所在的文件夹」本身，不下钻子文件夹，也不匹配父级/兄弟文件夹。
|
||
*/
|
||
function getValidFolders(filePath) {
|
||
const itemFolders = foldersOfItem(filePath);
|
||
if (itemFolders.length === 0) return null; // 未归入任何 Eagle 文件夹，则不限定
|
||
return new Set(itemFolders);
|
||
}
|
||
|
||
/** 判断目录是否为 Eagle 的 item 元数据文件夹（包含 metadata.json） */
|
||
function isEagleItemDir(dir) {
|
||
try { return fs.existsSync(path.join(dir, 'metadata.json')); } catch (e) { return false; }
|
||
}
|
||
|
||
/**
|
||
* 计算需要搜索的目录列表。
|
||
* Eagle 会把导入的每个文件拆分成独立的元数据文件夹（如 `images/<id>.info/`），
|
||
* 因此配套的骨骼/atlas/贴图可能位于不同的 item 文件夹中。
|
||
* 返回：当前 item 文件夹 + 其同级的所有 item 文件夹。
|
||
*/
|
||
function getSearchRoots(filePath) {
|
||
const roots = [];
|
||
const itemDir = path.dirname(filePath);
|
||
roots.push(itemDir);
|
||
if (isEagleItemDir(itemDir)) {
|
||
const parent = path.dirname(itemDir);
|
||
try {
|
||
for (const name of fs.readdirSync(parent)) {
|
||
const sub = path.join(parent, name);
|
||
try {
|
||
if (fs.statSync(sub).isDirectory() && isEagleItemDir(sub)) {
|
||
roots.push(sub);
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
}
|
||
return [...new Set(roots)];
|
||
}
|
||
|
||
/** 把库根目录 images/ 下所有 item 文件夹加入搜索根（去重）。
|
||
* 用于覆盖同伴位于不同 .info / 跨批次的情况（全库兜底）。 */
|
||
function buildRootsWithLibraryRoot(filePath, roots) {
|
||
const libRoot = findLibraryRoot(filePath);
|
||
if (!libRoot) return;
|
||
const imagesDir = path.join(libRoot, 'images');
|
||
try {
|
||
if (!fs.existsSync(imagesDir)) return;
|
||
for (const name of fs.readdirSync(imagesDir)) {
|
||
const sub = path.join(imagesDir, name);
|
||
try {
|
||
if (fs.statSync(sub).isDirectory() && isEagleItemDir(sub)) {
|
||
if (roots.indexOf(sub) === -1) roots.push(sub);
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
}
|
||
} catch (e) { /* ignore */ }
|
||
}
|
||
|
||
/**
|
||
* 在多个目录中收集所有 Spine 相关文件，返回 [{ name, fullPath }]。
|
||
* 若传入 validFolders（Eagle 逻辑文件夹 id 集合），则只保留位于这些文件夹内的 item，
|
||
* 从而把匹配范围限定在「选中文件所在的 Eagle 文件夹及其子文件夹」内。
|
||
*/
|
||
function collectSpineFiles(roots, validFolders) {
|
||
const seen = new Set();
|
||
const out = [];
|
||
for (const root of roots) {
|
||
// Eagle 库内只允许真实位置仍处于 images/ 下的普通 .info 目录。
|
||
// 库外仅用于本地测试，仍把当前目录作为唯一边界。
|
||
const probe = path.join(root, '__spineviewer_probe__');
|
||
const libRoot = findLibraryRoot(probe);
|
||
if (libRoot) {
|
||
try {
|
||
const imagesReal = realpath(path.join(libRoot, 'images'));
|
||
const rootReal = realpath(root);
|
||
if (!isPathInside(imagesReal, rootReal) || !isEagleItemDir(root)) continue;
|
||
} catch (e) { continue; }
|
||
}
|
||
let entries;
|
||
try { entries = fs.readdirSync(root); } catch (e) { continue; }
|
||
for (const name of entries) {
|
||
if (!extOf(name)) continue; // 只关心 Spine 相关扩展
|
||
// readdir 的结果也必须通过 realpath 边界校验，不能信任 .info 中的符号链接。
|
||
const full = resolveFileWithin(root, name, false);
|
||
if (!full) continue;
|
||
// 排除 Eagle 回收站中已删除的项
|
||
if (isItemDeleted(full)) continue;
|
||
if (validFolders && validFolders.size) {
|
||
const itemFolders = foldersOfItem(full);
|
||
if (!itemFolders.some((f) => validFolders.has(f))) continue; // 不在允许的文件夹内
|
||
}
|
||
if (seen.has(full)) continue;
|
||
seen.add(full);
|
||
out.push({ name, fullPath: full });
|
||
}
|
||
}
|
||
return out;
|
||
}
|
||
|
||
/**
|
||
* 缩略图批量生成时，同一时刻会有很多 atlas/json/skel 回调。对全库文件清单做一个
|
||
* 很短的缓存，下一轮轮询仍会重新扫描，因此既降低大文件夹导入开销，也不会漏掉
|
||
* 正在落盘的新文件。
|
||
*/
|
||
function collectSpineFilesCached(filePath, roots, refresh) {
|
||
const libRoot = findLibraryRoot(filePath);
|
||
// Outside an Eagle library, sibling asset folders are independent search
|
||
// scopes. Sharing their parent as a cache key can return another skeleton.
|
||
const key = libRoot || JSON.stringify([...roots].sort());
|
||
const now = Date.now();
|
||
const cached = fileIndexCache.get(key);
|
||
if (!refresh && cached && now - cached.time < 1500) return cached.files;
|
||
const files = collectSpineFiles(roots, null);
|
||
fileIndexCache.set(key, { time: now, files });
|
||
return files;
|
||
}
|
||
|
||
/**
|
||
* 修正不可靠的源路径。
|
||
* Eagle 传给缩略图 handler 的 src 有时指向一个已清理/不存在的 `.info` 目录
|
||
* （例如其内部临时工作目录）。此时按文件名在整个库 images/ 下找到真实存在的
|
||
* 源文件，作为后续资源发现的基准。
|
||
*/
|
||
function resolveRealSource(filePath) {
|
||
// 源目录存在且是有效 item 目录 → 直接用
|
||
const dir = path.dirname(filePath);
|
||
if (isEagleItemDir(dir)) return filePath;
|
||
const name = path.basename(filePath);
|
||
const libRoot = findLibraryRoot(filePath);
|
||
if (!libRoot) return filePath;
|
||
const imagesDir = path.join(libRoot, 'images');
|
||
try {
|
||
if (!fs.existsSync(imagesDir)) return filePath;
|
||
// 优先找“文件名 + 类型”匹配的真实文件。若存在同名文件，返回它所在目录，
|
||
// 以便后续 getSearchRoots/selectBest 能借助其 folders/btime 精确匹配。
|
||
let fallback = null;
|
||
for (const d of fs.readdirSync(imagesDir)) {
|
||
const sub = path.join(imagesDir, d);
|
||
if (!isEagleItemDir(sub)) continue;
|
||
const cand = path.join(sub, name);
|
||
if (fs.existsSync(cand)) {
|
||
// 优先选择未被删除的项
|
||
if (!isItemDeleted(cand)) return cand;
|
||
if (!fallback) fallback = cand;
|
||
}
|
||
}
|
||
if (fallback) return fallback;
|
||
} catch (e) { /* ignore */ }
|
||
return filePath;
|
||
}
|
||
|
||
/**
|
||
* 发现与所选文件 related 的 Spine 资源（跨 Eagle 多个 item 文件夹）。
|
||
* 返回 { skeletonPath, atlasPath, texturePaths, base, isBinary, ... }
|
||
* - texturePaths: { atlas 中引用的贴图名 -> 绝对路径 }
|
||
*/
|
||
function discoverAssets(filePath, options) {
|
||
options = options || {};
|
||
const strictStem = !!options.strictStem;
|
||
const requestedCrossBatch = !!options.allowCrossBatch;
|
||
const maxCrossBatchDeltaMs = Math.max(30000, Number(options.maxCrossBatchDeltaMs) || 5 * 60 * 1000);
|
||
filePath = resolveRealSource(filePath);
|
||
const selected = path.basename(filePath);
|
||
const selectedStem = normalizeStem(selected);
|
||
// 先扫码“选中 item 文件夹 + 同级所有 .info”（精确、不跨批次）。
|
||
let roots;
|
||
if (Array.isArray(options.searchRoots) && options.searchRoots.length) {
|
||
roots = [...new Set(options.searchRoots.map((root) => path.resolve(root)))];
|
||
} else {
|
||
roots = getSearchRoots(filePath);
|
||
// 兼容旧的非查询调用：扩展到整个库。查看器会传入 Eagle API
|
||
// 明确列举的候选 item 目录，避免每次预览扫描整库。
|
||
buildRootsWithLibraryRoot(filePath, roots);
|
||
}
|
||
|
||
// 导入时 Eagle 会先创建各个 .info，再异步写 folders。严格模式必须把尚未写入
|
||
// folders 的同批资源也纳入候选，之后用 metadata.json 的 birthtime 精确配对。
|
||
const validFolders = getValidFolders(filePath);
|
||
// 导入瞬间 folders 可能尚未写入。没有明确 Eagle 文件夹 ID 时禁止跨批次，
|
||
// 否则单独导入的同名 JSON 会借用库中任意旧 atlas 生成错误缩略图。
|
||
const allowCrossBatch = requestedCrossBatch && !!(validFolders && validFolders.size);
|
||
const allowedImportDelta = allowCrossBatch ? maxCrossBatchDeltaMs : 30000;
|
||
let files;
|
||
if (strictStem) {
|
||
const allFiles = collectSpineFilesCached(filePath, roots, options.refreshIndex);
|
||
// 无论是否允许跨批次，都必须限定在同一个 Eagle 文件夹内。同名素材很常见
|
||
//（同一套资源的 3.6 与 4.0 导出、同一角色的不同批次），只按文件名 stem
|
||
// 匹配会配到别的版本，渲染时要么区域找不到，要么贴图坐标整个错位。
|
||
files = validFolders && validFolders.size
|
||
? allFiles.filter((f) => foldersOfItem(f.fullPath).some((id) => validFolders.has(id)))
|
||
: allFiles;
|
||
} else {
|
||
files = collectSpineFiles(roots, validFolders);
|
||
}
|
||
|
||
let skeletonFiles = files.filter((f) => isSkeletonFile(f.name));
|
||
const atlasFiles = files.filter((f) => isAtlasFile(f.name));
|
||
const textureFiles = files.filter((f) => isTextureFile(f.name));
|
||
// 导入缩略图始终按同名资源链匹配。先按 stem 缩小候选，再检查 JSON 内容，
|
||
// 避免每个回调都解析库中所有普通 JSON。
|
||
if (strictStem) {
|
||
skeletonFiles = skeletonFiles.filter((f) => normalizeStem(f.name) === selectedStem);
|
||
}
|
||
|
||
// 区分“骨架 json”和“普通 json”：只保留形似骨架的 json
|
||
const realSkeletonFiles = skeletonFiles.filter((f) => {
|
||
if (f.name.toLowerCase().endsWith('.json')) return looksLikeSkeletonJson(f.fullPath);
|
||
return true;
|
||
});
|
||
|
||
// 工具：优先选择与 refFile 同一批入库的候选，再看 Eagle 逻辑文件夹及素材时间。
|
||
// 这可区分同一文件夹中多次导入的同名 Spine 导出，又不受素材原始时间影响。
|
||
const selectBest = (cands, refFile) => {
|
||
if (!cands || cands.length === 0) return null;
|
||
const refFolders = foldersOfItem(refFile);
|
||
const refImportTime = importTimeOf(refFile);
|
||
const refBtime = btimeOf(refFile);
|
||
const ranked = cands.map((c) => {
|
||
const cFolders = foldersOfItem(c.fullPath);
|
||
return {
|
||
c,
|
||
importDelta: refImportTime ? Math.abs(importTimeOf(c.fullPath) - refImportTime) : Number.MAX_SAFE_INTEGER,
|
||
sameFolder: refFolders.length && cFolders.some((f) => refFolders.indexOf(f) !== -1) ? 1 : 0,
|
||
btimeDelta: refBtime ? Math.abs(btimeOf(c.fullPath) - refBtime) : Number.MAX_SAFE_INTEGER,
|
||
};
|
||
});
|
||
ranked.sort((a, b) => allowCrossBatch
|
||
? (b.sameFolder - a.sameFolder || a.importDelta - b.importDelta || a.btimeDelta - b.btimeDelta || a.c.fullPath.localeCompare(b.c.fullPath))
|
||
: (a.importDelta - b.importDelta || b.sameFolder - a.sameFolder || a.btimeDelta - b.btimeDelta || a.c.fullPath.localeCompare(b.c.fullPath))
|
||
);
|
||
return ranked[0].c;
|
||
};
|
||
|
||
// 辅助：读取候选 atlas 的格式家族，以及候选骨骼的版本家族
|
||
const familyOfAtlas = (f) => { try { return atlasFamily(fs.readFileSync(f.fullPath, 'utf8')); } catch (e) { return null; } };
|
||
const familyOfSkel = (f) => { try { return versionFamily(detectVersion(f.fullPath)); } catch (e) { return null; } };
|
||
|
||
// 选中的文件若是 atlas，则读取其格式家族，用于匹配同家族的骨骼
|
||
const selectedAtlasFamily = isAtlasFile(selected)
|
||
? (() => { try { return atlasFamily(fs.readFileSync(filePath, 'utf8')); } catch (e) { return null; } })()
|
||
: null;
|
||
|
||
// 1) 骨骼文件
|
||
let skeleton = null;
|
||
// 若选中的就是骨骼文件，务必使用它本身（它的版本即最终版本）
|
||
if (isSkeletonFile(selected)) {
|
||
skeleton = realSkeletonFiles.find((f) => f.fullPath === filePath) ||
|
||
realSkeletonFiles.find((f) => f.name === selected) || null;
|
||
}
|
||
if (!skeleton) {
|
||
// 依选中 stem 匹配；优先与选中 atlas 同家族（3x/4x），再按同文件夹/同批导入
|
||
let cands = realSkeletonFiles.filter((f) => normalizeStem(f.name) === selectedStem);
|
||
if (selectedAtlasFamily && cands.length > 1) {
|
||
const same = cands.filter((f) => familyOfSkel(f) === selectedAtlasFamily);
|
||
if (same.length > 0) cands = same;
|
||
}
|
||
skeleton = cands.length > 0 ? selectBest(cands, filePath) : null;
|
||
}
|
||
if (!skeleton && realSkeletonFiles.length > 0) {
|
||
if (strictStem) {
|
||
skeleton = null;
|
||
} else {
|
||
// 忽略 stem：优先与选中 atlas 同家族，再按入库批次选取
|
||
let cands = realSkeletonFiles;
|
||
if (selectedAtlasFamily) {
|
||
const same = cands.filter((f) => familyOfSkel(f) === selectedAtlasFamily);
|
||
if (same.length > 0) cands = same;
|
||
}
|
||
skeleton = selectBest(cands, filePath);
|
||
}
|
||
}
|
||
|
||
|
||
// 2) atlas 文件 —— 优先与骨骼版本家族一致（3x/4x），避免 3.8 骨骼配 4x atlas
|
||
let atlas = null;
|
||
if (isAtlasFile(selected)) {
|
||
atlas = atlasFiles.find((f) => f.fullPath === filePath) ||
|
||
atlasFiles.find((f) => f.name === selected) || null;
|
||
}
|
||
// 统一的候选选择：优先“与骨骼同家族(3x/4x)”的 atlas，再按“同文件夹 + 最近 btime”挑选。
|
||
// 家族过滤无条件优先，避免 4x 骨骼配到 3x 图集（会导致 UV/坐标错乱）。
|
||
const pickAtlas = (cands, refFile) => {
|
||
if (!cands || cands.length === 0) return null;
|
||
const skelFamily = skeleton ? familyOfSkel(skeleton) : null;
|
||
if (skelFamily) {
|
||
const same = cands.filter((f) => familyOfAtlas(f) === skelFamily);
|
||
if (same.length > 0) cands = same;
|
||
}
|
||
return selectBest(cands, refFile);
|
||
};
|
||
|
||
if (!atlas) {
|
||
let cands = atlasFiles.filter((f) => normalizeStem(f.name) === selectedStem);
|
||
atlas = pickAtlas(cands, filePath);
|
||
}
|
||
if (!atlas && skeleton) {
|
||
const skelStem = normalizeStem(skeleton.name);
|
||
let cands = atlasFiles.filter((f) => normalizeStem(f.name) === skelStem);
|
||
atlas = pickAtlas(cands, skeleton.fullPath);
|
||
}
|
||
if (!atlas && skeleton) {
|
||
if (strictStem) {
|
||
atlas = null;
|
||
} else {
|
||
// 忽略 stem：用与骨骼同家族且同批入库的 atlas
|
||
atlas = pickAtlas(atlasFiles, skeleton.fullPath);
|
||
}
|
||
}
|
||
if (!atlas && !strictStem && atlasFiles.length === 1) atlas = atlasFiles[0];
|
||
|
||
// 严格模式用于导入缩略图：配套骨骼和图集应由同一次拖入创建。若时间差
|
||
// 过大，说明新同伴还没落盘，返回缺失让调用方继续等待，不能借用旧同名资源。
|
||
if (strictStem && skeleton && atlas) {
|
||
const pairDelta = Math.abs(importTimeOf(skeleton.fullPath) - importTimeOf(atlas.fullPath));
|
||
if (pairDelta > allowedImportDelta) {
|
||
if (isAtlasFile(selected)) skeleton = null;
|
||
else atlas = null;
|
||
}
|
||
}
|
||
|
||
// 3) 解析 atlas 引用的贴图路径（多个同名贴图时，优先与 atlas 同文件夹/同批导入的）
|
||
let texturePaths = {};
|
||
if (atlas) {
|
||
let text = '';
|
||
try { text = fs.readFileSync(atlas.fullPath, 'utf8'); } catch (e) { /* ignore */ }
|
||
const pageNames = parseAtlasPages(text);
|
||
const atlasDir = path.dirname(atlas.fullPath); // atlas 所在 .info 目录
|
||
for (const pn of pageNames) {
|
||
// 1) 允许 atlas 所在 .info 目录内的安全相对路径；realpath 必须仍在目录内。
|
||
const inAtlasDir = resolveAtlasTextureFile(atlasDir, pn);
|
||
if (inAtlasDir) {
|
||
texturePaths[pn] = inAtlasDir;
|
||
continue;
|
||
}
|
||
// 2) 跨素材时只能使用上面已枚举并验证的 Eagle 素材，不能由 atlas 拼接路径。
|
||
const pageFileName = path.posix.basename(pn);
|
||
let cands = textureFiles.filter((f) => f.name.toLowerCase() === pageFileName.toLowerCase());
|
||
if (cands.length === 0) cands = textureFiles.filter((f) => normalizeStem(f.name) === normalizeStem(pageFileName));
|
||
let hit = selectBest(cands, atlas.fullPath);
|
||
if (strictStem && hit && Math.abs(importTimeOf(hit.fullPath) - importTimeOf(atlas.fullPath)) > allowedImportDelta) hit = null;
|
||
if (hit) texturePaths[pn] = hit.fullPath;
|
||
}
|
||
}
|
||
|
||
const base = skeleton ? normalizeStem(skeleton.name) : (atlas ? normalizeStem(atlas.name) : selectedStem);
|
||
const skelLower = skeleton ? skeleton.name.toLowerCase() : '';
|
||
const skeletonIsBinary = skelLower.endsWith('.skel') || skelLower.endsWith('.skel.bytes');
|
||
return {
|
||
skeletonPath: skeleton ? skeleton.fullPath : null,
|
||
atlasPath: atlas ? atlas.fullPath : null,
|
||
texturePaths,
|
||
base,
|
||
isBinary: skeletonIsBinary,
|
||
skeletonCandidates: realSkeletonFiles.map((f) => f.name),
|
||
skeletonCandidatePaths: realSkeletonFiles.map((f) => f.fullPath),
|
||
atlasCandidates: atlasFiles.map((f) => f.name),
|
||
atlasCandidatePaths: atlasFiles.map((f) => f.fullPath),
|
||
textureCandidates: textureFiles.map((f) => f.name),
|
||
};
|
||
}
|
||
|
||
/** 从 atlas 文本中解析出引用的贴图页面文件名 */
|
||
function parseAtlasPages(atlasText) {
|
||
const pages = [];
|
||
if (!atlasText) return pages;
|
||
const lines = atlasText.split(/\r?\n/);
|
||
// atlas 中每个页面以一行“xxx.png”之类的文件名开始
|
||
for (let i = 0; i < lines.length; i++) {
|
||
const line = lines[i].trim();
|
||
if (/\.(png|jpg|jpeg|webp)$/i.test(line) && !/[=,:]/.test(line)) {
|
||
pages.push(validateAtlasPageName(line));
|
||
} else if (line === '') {
|
||
// 空白行之后的下一个非空行可能是下一页文件名
|
||
continue;
|
||
}
|
||
}
|
||
return [...new Set(pages)];
|
||
}
|
||
|
||
/**
|
||
* 读取 Atlas 页面声明的预乘设置。Spine 4.x 会为每个页面写入
|
||
* `pma:true/false`；旧版 Atlas 通常没有该字段，此时返回 undefined。
|
||
* Spine 的一次导出会让所有页面使用同一设置。若遇到手工拼接且声明冲突
|
||
* 的 Atlas，采用第一个页面的声明，保持与页面/区域读取顺序一致。
|
||
*/
|
||
function parseAtlasPma(atlasText) {
|
||
if (typeof atlasText !== 'string') return undefined;
|
||
const matches = Array.from(atlasText.matchAll(/^\s*pma\s*:\s*(true|false)\s*$/gim));
|
||
return matches.length ? matches[0][1].toLowerCase() === 'true' : undefined;
|
||
}
|
||
|
||
/** 找到应在首次预览时使用的皮肤：defaultSkin、名为 default 的皮肤、第一个皮肤。 */
|
||
function preferredSkin(skeletonData) {
|
||
if (!skeletonData) return null;
|
||
if (skeletonData.defaultSkin) return skeletonData.defaultSkin;
|
||
const skins = skeletonData.skins || [];
|
||
return skins.find((skin) => skin && skin.name === 'default') || skins[0] || null;
|
||
}
|
||
|
||
/** 应用皮肤并按 setup pose 重新解析槽位附件，跨 Spine 3.4–4.3 使用。 */
|
||
function applySkin(skeleton, skin) {
|
||
if (!skeleton || !skin) return false;
|
||
if (typeof skeleton.setSkin === 'function') skeleton.setSkin(skin);
|
||
else if (typeof skeleton.setSkinByName === 'function') skeleton.setSkinByName(skin.name);
|
||
else return false;
|
||
if (typeof skeleton.setSlotsToSetupPose === 'function') skeleton.setSlotsToSetupPose();
|
||
else if (typeof skeleton.setToSetupPose === 'function') skeleton.setToSetupPose();
|
||
return true;
|
||
}
|
||
|
||
const spineUtilsApi = {
|
||
SKELETON_EXTS,
|
||
ATLAS_EXTS,
|
||
TEXTURE_EXTS,
|
||
ALL_EXTS,
|
||
extOf,
|
||
isSkeletonFile,
|
||
isAtlasFile,
|
||
isTextureFile,
|
||
stemOf,
|
||
normalizeStem,
|
||
DEFAULT_SUFFIXES,
|
||
SUFFIX_MAX_LENGTH,
|
||
normalizeSuffixName,
|
||
setSuffixes,
|
||
getSuffixes,
|
||
getCustomSuffixes,
|
||
detectVersion,
|
||
detectVersionFromJson,
|
||
detectVersionFromBuffer,
|
||
chooseRuntimeDir,
|
||
classifySkeletonJson,
|
||
looksLikeSkeletonJson,
|
||
discoverAssets,
|
||
parseAtlasPages,
|
||
validateAtlasPageName,
|
||
resolveAtlasTextureFile,
|
||
parseAtlasPma,
|
||
preferredSkin,
|
||
applySkin,
|
||
isEagleItemDir,
|
||
getSearchRoots,
|
||
collectSpineFiles,
|
||
foldersOfItem,
|
||
findLibraryRoot,
|
||
readFolderInfo,
|
||
getValidFolders,
|
||
splitCompoundName,
|
||
mtimeOf,
|
||
btimeOf,
|
||
importTimeOf,
|
||
versionFamily,
|
||
atlasFamily,
|
||
itemMeta,
|
||
isItemDeleted,
|
||
};
|
||
|
||
if (typeof window !== 'undefined') window.SpineUtils = spineUtilsApi;
|
||
else if (typeof module !== 'undefined' && module.exports) module.exports = spineUtilsApi;
|
||
|
||
})();
|