@fps-games/vfx 0.1.1

package/tooling/vfx-cli.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// @fps/vfx CLI:把库特效以「re-export 桩 + 本地 vfx-params.json」装进项目(plan §6.2/§16 混合分发 模型C),
+// 并管理版本升级(issue #4)。消费方典型调用:
+//   node node_modules/@fps/vfx/tooling/vfx-cli.mjs <cmd> --project .
+//
+//   list                                      列出库里可用特效
+//   add <id> [--project <dir>] [--force]      装一个特效(桩 + vfx-params.json + .vfx-source.json)
+//   outdated [--project <dir>]                对比项目钉的 @fps/vfx 版本 / 各特效 provenance vs 最新
+//   update [<id>] [--project <dir>] [--to vX.Y.Z]
+//                                             升级:改 package.json 的 @fps/vfx git-tag ref + 重同步桩
+//                                             + 不动 vfx-params.json + 打印 CHANGELOG 区间(然后 pnpm install)
+import { readdirSync, statSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const LIB_EFFECTS = join(LIB_ROOT, 'packages', 'effects');
+const LIB_VERSION = (() => { try { return JSON.parse(readFileSync(join(LIB_ROOT, 'package.json'), 'utf8')).version; } catch { return '0.0.0'; } })();
+
+const [, , cmd, ...rest] = process.argv;
+const VALUED_FLAGS = new Set(['--project', '--to']); // 这些 flag 后跟一个值,值不算 positional
+const flags = new Set(rest.filter((a) => a.startsWith('--')));
+const positional = [];
+for (let i = 0; i < rest.length; i++) {
+  const a = rest[i];
+  if (a.startsWith('--')) { if (VALUED_FLAGS.has(a)) i++; continue; }
+  positional.push(a);
+}
+function flagVal(name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
+const projectRoot = resolve(flagVal('--project') ?? process.cwd());
+const force = flags.has('--force');
+
+// ── 通用 ──────────────────────────────────────────────────────────────────────
+function libEffectIds() {
+  return readdirSync(LIB_EFFECTS).filter((e) => {
+    try { return statSync(join(LIB_EFFECTS, e)).isDirectory() && existsSync(join(LIB_EFFECTS, e, 'index.ts')); } catch { return false; }
+  });
+}
+function stub(id) {
+  return `// @fps/vfx re-export 桩(代码/资源在包内;本地仅 vfx-params.json + 此桩)。\nexport * from '@fps/vfx/effects/${id}';\n`;
+}
+function effectsDestDir() { return join(projectRoot, 'src', 'assets', 'vfx', 'effects'); }
+function provenance(id, version) {
+  return JSON.stringify({ id, source: '@fps/vfx', version }, null, 2) + '\n';
+}
+function normVer(v) { return String(v ?? '').replace(/^v/, ''); }
+function semverCmp(a, b) {
+  const pa = normVer(a).split('.').map(Number); const pb = normVer(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); }
+  return 0;
+}
+
+// 读项目 package.json 里的 @fps/vfx 依赖(原始文本 + 解析值)。
+function readProjectVfxDep() {
+  const p = join(projectRoot, 'package.json');
+  if (!existsSync(p)) return null;
+  const raw = readFileSync(p, 'utf8');
+  const json = JSON.parse(raw);
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    const val = json[field]?.['@fps/vfx'];
+    if (val) return { path: p, raw, json, field, value: val };
+  }
+  return { path: p, raw, json, field: null, value: null };
+}
+function pinFromValue(value) { const m = String(value ?? '').match(/#v?(\d+\.\d+\.\d+)/); return m ? m[1] : null; }
+function repoUrlFromValue(value) { return String(value ?? '').replace(/#.*$/, ''); }
+
+function latestRemoteTag(repoUrl) {
+  if (!repoUrl) return null;
+  try {
+    const out = execFileSync('git', ['ls-remote', '--tags', repoUrl], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const tags = [...out.matchAll(/refs\/tags\/v(\d+\.\d+\.\d+)(?:\^\{\})?$/gm)].map((m) => m[1]);
+    if (!tags.length) return null;
+    return tags.sort(semverCmp).at(-1);
+  } catch { return null; }
+}
+
+function installedEffects() {
+  const dir = effectsDestDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((e) => {
+    try { return statSync(join(dir, e)).isDirectory() && existsSync(join(dir, e, 'index.ts')); } catch { return false; }
+  }).map((id) => {
+    const srcFile = join(dir, id, '.vfx-source.json');
+    let version = null;
+    if (existsSync(srcFile)) { try { version = JSON.parse(readFileSync(srcFile, 'utf8')).version ?? null; } catch { /* ignore */ } }
+    return { id, version };
+  });
+}
+
+// 从库 CHANGELOG.md 抽 (from, to] 区间的版本区块。
+function changelogRange(fromVersion, toVersion) {
+  const p = join(LIB_ROOT, 'CHANGELOG.md');
+  if (!existsSync(p)) return null;
+  const text = readFileSync(p, 'utf8');
+  const blocks = [];
+  const re = /^## v(\d+\.\d+\.\d+)[^\n]*$/gm;
+  const heads = [...text.matchAll(re)];
+  for (let i = 0; i < heads.length; i++) {
+    const ver = heads[i][1];
+    const start = heads[i].index;
+    const end = i + 1 < heads.length ? heads[i + 1].index : text.length;
+    const includeAbove = fromVersion ? semverCmp(ver, fromVersion) > 0 : true;
+    if (includeAbove && (toVersion ? semverCmp(ver, toVersion) <= 0 : true)) {
+      blocks.push(text.slice(start, end).trimEnd());
+    }
+  }
+  return blocks.length ? blocks.join('\n\n') : null;
+}
+
+// ── add ───────────────────────────────────────────────────────────────────────
+function add(id) {
+  if (!existsSync(join(LIB_EFFECTS, id))) { console.error(`✗ 库中无特效 "${id}"。可用:run "list"。`); process.exit(1); }
+  const destDir = join(effectsDestDir(), id);
+  const stubPath = join(destDir, 'index.ts');
+  const paramsPath = join(destDir, 'vfx-params.json');
+  const libParams = join(LIB_EFFECTS, id, 'vfx-params.json');
+
+  if (existsSync(stubPath) && !force) { console.error(`✗ "${id}" 已存在(${destDir});--force 覆盖。`); process.exit(1); }
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync(stubPath, stub(id));
+
+  if (!existsSync(paramsPath)) {
+    if (existsSync(libParams)) copyFileSync(libParams, paramsPath);
+    else writeFileSync(paramsPath, JSON.stringify({ schemaVersion: 'vfx-params/1.0', effectId: id, params: {} }, null, 2) + '\n');
+  } else if (force) {
+    console.warn(`  ! 保留已存在的 vfx-params.json(项目调参不覆盖,即便 --force)。`);
+  }
+  writeFileSync(join(destDir, '.vfx-source.json'), provenance(id, LIB_VERSION));
+  console.log(`✓ 已装 "${id}" → ${destDir}\n  桩 + vfx-params.json(已存在则保留)+ .vfx-source.json(v${LIB_VERSION})`);
+  console.log('  提示:项目侧 src/assets/vfx/index.ts 用 glob+buildRegistry 自动发现,无需手动注册。');
+}
+
+// ── outdated ──────────────────────────────────────────────────────────────────
+function outdated() {
+  const dep = readProjectVfxDep();
+  if (!dep) { console.error(`✗ ${projectRoot} 下无 package.json。`); process.exit(1); }
+  const pin = pinFromValue(dep.value);
+  const repoUrl = repoUrlFromValue(dep.value);
+  const remote = latestRemoteTag(repoUrl); // 只查一次
+  const latest = remote ?? LIB_VERSION;
+  const latestSource = remote ? '远端最新 tag' : `本库版本(远端不可达,回退)`;
+
+  console.log(`项目:${projectRoot}`);
+  console.log(`@fps/vfx 钉版本:${pin ? `v${pin}` : '(未钉 / 非 git-tag)'}  →  最新:v${latest}(${latestSource})`);
+  const depBehind = pin && semverCmp(pin, latest) < 0;
+  console.log(depBehind ? `⬆ 依赖落后:可升级到 v${latest}(\`vfx update --to v${latest}\` + pnpm install)` : `✓ 依赖已是最新(或无法判定)。`);
+
+  const effects = installedEffects();
+  if (effects.length) {
+    console.log(`\n已装特效(${effects.length}):`);
+    for (const e of effects.sort((a, b) => a.id.localeCompare(b.id))) {
+      const v = e.version;
+      const tag = v == null ? '无 provenance(早期批量安装)' : (semverCmp(v, latest) < 0 ? `v${v} ⬆ 落后` : `v${v} ✓`);
+      console.log(`  - ${e.id}  [${tag}]`);
+    }
+    console.log(`\n注:模型C 下特效代码/资源在 @fps/vfx 包内,真实版本由上面的依赖钉版本决定;`);
+    console.log(`    .vfx-source.json 仅作 add 时的来源记录,落后不影响运行(随依赖升级即同步)。`);
+  } else {
+    console.log(`\n(项目 ${effectsDestDir()} 下暂无已装特效)`);
+  }
+}
+
+// ── update ────────────────────────────────────────────────────────────────────
+function update(onlyId) {
+  const dep = readProjectVfxDep();
+  if (!dep) { console.error(`✗ ${projectRoot} 下无 package.json。`); process.exit(1); }
+  const oldPin = pinFromValue(dep.value);
+  const repoUrl = repoUrlFromValue(dep.value);
+  const toFlag = flagVal('--to');
+  const target = normVer(toFlag ?? latestRemoteTag(repoUrl) ?? LIB_VERSION);
+
+  // 1) 改 package.json 的 @fps/vfx git-tag ref(保留原 url 与格式,仅换 #ref)。
+  const isGitDep = /(^git\+|:\/\/|github\.com|\.git)/.test(dep.value ?? '');
+  if (dep.field && dep.value && (/#/.test(dep.value) || isGitDep)) {
+    let newValue;
+    if (/#/.test(dep.value)) newValue = dep.value.replace(/#.*$/, `#v${target}`);
+    else newValue = `${dep.value}#v${target}`;
+    if (newValue !== dep.value) {
+      // 原文本就地替换,避免重排整份 package.json;用替换函数避免 newValue 里的 $ 被当替换记号。
+      const depValRe = new RegExp(`("@fps/vfx"\\s*:\\s*")${dep.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(")`);
+      const newRaw = dep.raw.replace(depValRe, (_m, p1, p2) => `${p1}${newValue}${p2}`);
+      if (newRaw !== dep.raw) {
+        writeFileSync(dep.path, newRaw);
+        console.log(`✓ package.json:@fps/vfx ${oldPin ? `#v${oldPin}` : dep.value} → #v${target}`);
+      } else {
+        console.warn(`! 未能就地替换 @fps/vfx 依赖文本,请手动把 ref 改成 #v${target}。`);
+      }
+    } else {
+      console.log(`= package.json:@fps/vfx 已是 #v${target}。`);
+    }
+  } else if (dep.field && dep.value) {
+    console.warn(`! @fps/vfx 依赖 "${dep.value}" 不是 git-tag 形式,跳过 ref 升级(仅重同步桩)。如需固定版本,请手动改成 git+ssh://…#v${target}。`);
+  } else {
+    console.warn(`! 项目 package.json 未声明 @fps/vfx 依赖,跳过 ref 升级(仅同步桩)。`);
+  }
+
+  // 2) 重同步桩 + bump .vfx-source.json(永不动 vfx-params.json)。
+  const effects = installedEffects();
+  const targets = onlyId ? effects.filter((e) => e.id === onlyId) : effects;
+  if (onlyId && !targets.length) { console.error(`✗ 项目未安装 "${onlyId}";请先 add。`); process.exit(1); }
+  for (const e of targets) {
+    const d = join(effectsDestDir(), e.id);
+    writeFileSync(join(d, 'index.ts'), stub(e.id));               // 同步桩(export 路径可能变)
+    writeFileSync(join(d, '.vfx-source.json'), provenance(e.id, target)); // 记新版本
+    // vfx-params.json 不动(项目所有)
+  }
+  console.log(`✓ 已重同步 ${targets.length} 个特效的桩 + provenance → v${target};vfx-params.json 未动(项目调参)。`);
+
+  // 3) 打印 CHANGELOG 区间。
+  const range = changelogRange(oldPin, target);
+  if (range) { console.log(`\n── CHANGELOG ${oldPin ? `v${oldPin} → ` : ''}v${target} ──\n${range}\n`); }
+
+  console.log(`\n下一步:\`pnpm install\`(拉取 @fps/vfx#v${target} 新代码/资源)。`);
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────────
+if (cmd === 'list') {
+  console.log(`@fps/vfx 可用特效(v${LIB_VERSION}):`);
+  for (const id of libEffectIds().sort()) console.log(`  - ${id}`);
+} else if (cmd === 'add') {
+  if (!positional[0]) { console.error('用法: add <id> [--project <dir>] [--force]'); process.exit(1); }
+  add(positional[0]);
+} else if (cmd === 'outdated') {
+  outdated();
+} else if (cmd === 'update') {
+  update(positional[0]); // id 可选;无则更新全部 + 升依赖 ref
+} else {
+  console.log('用法: node tooling/vfx-cli.mjs <list|add|outdated|update> ...');
+  process.exit(cmd ? 1 : 0);
+}

package/tooling/vfx-package-resolution.mjs

@@ -0,0 +1,28 @@
+// @fps/vfx 的 Vite 接入助手(plan §18.3:克隆 editor 蓝图,简化为单包)。
+// 消费方 vite.config:
+//   import { createVfxLibrarySourceAlias, VFX_BABYLON_DEDUPE } from '@fps/vfx/vite'(或本文件路径)
+//   resolve: { alias: [...createVfxLibrarySourceAlias(process.env.FPS_VFX_LIBRARY_REPO)], dedupe: [...VFX_BABYLON_DEDUPE] }
+import { resolve } from 'node:path';
+
+// Babylon 必须与项目去重为单实例(否则特效与场景用不同 Babylon → 渲染/类型错乱)。
+export const VFX_BABYLON_DEDUPE = ['@babylonjs/core', '@babylonjs/loaders'];
+
+/**
+ * 源码模式:把 `@fps/vfx` / `@fps/vfx/effects/<id>` 别名到本地库源(供 dev / SDK 联调)。
+ * @param {string} libRepoRoot fps-vfx-library 仓库根(通常来自 process.env.FPS_VFX_LIBRARY_REPO)
+ * @returns vite alias 数组(给 resolve.alias)
+ */
+export function createVfxLibrarySourceAlias(libRepoRoot) {
+  if (!libRepoRoot) {
+    throw new Error('[vfx] createVfxLibrarySourceAlias: libRepoRoot 为空(设置 FPS_VFX_LIBRARY_REPO 指向 fps-vfx-library 仓库根)。');
+  }
+  const pkgs = resolve(libRepoRoot, 'packages');
+  return [
+    // 子路径:@fps/vfx/effects/<id> → packages/effects/<id>/index.ts
+    { find: /^@fps\/vfx\/effects\/(.+)$/, replacement: resolve(pkgs, 'effects') + '/$1/index.ts' },
+    // 根入口:@fps/vfx → packages/index.ts
+    { find: /^@fps\/vfx$/, replacement: resolve(pkgs, 'index.ts') },
+    // vite 助手子路径(本文件)
+    { find: /^@fps\/vfx\/vite$/, replacement: resolve(libRepoRoot, 'tooling', 'vfx-package-resolution.mjs') },
+  ];
+}