@fps-games/vfx 0.1.1

package/packages/env.particle.forest_edge_fog/provenance/asset-map.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": "vfx-asset-map/1.0",
+  "generatedAt": "2026-05-20T09:28:52.237Z",
+  "sourcePackage": "vfx-intermediate/cocos-babylon-packages/effect_evn_fog",
+  "policy": {
+    "runtimeAssetsRoot": "assets/",
+    "sourceAssetsRoot": "source/",
+    "note": "assets/ contains files loaded by Babylon runtime. source/cocos/assets/ preserves the original Cocos asset tree for traceability and reconversion."
+  },
+  "entries": [
+    {
+      "id": "yuan",
+      "kind": "texture",
+      "group": "textures",
+      "role": "babylon-runtime",
+      "runtimeUse": true,
+      "packagePath": "assets/textures/yuan.png",
+      "sourcePackagePath": "assets/textures/yuan.png",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/mat/yuan.png",
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/mat/yuan.png",
+      "sourceId": "d48ae210-4e88-4021-b408-164a096c2587@6c48a",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/Effect_Evn_Fog/mat/yuan.png"
+    },
+    {
+      "id": "f12a23c4_b924_4322_a260_3d982428f1e8",
+      "kind": "texture",
+      "group": "textures",
+      "role": "babylon-runtime",
+      "runtimeUse": true,
+      "packagePath": "assets/textures/f12a23c4-b924-4322-a260-3d982428f1e8.png",
+      "sourcePackagePath": "assets/textures/f12a23c4-b924-4322-a260-3d982428f1e8.png",
+      "sourceArchivePath": null,
+      "sourcePath": "/Users/admin/Code/FPS/fps-vfx-agent-cocos-to-babylon/scaffolds/cocos-vfx-scaffold/library/f1/f12a23c4-b924-4322-a260-3d982428f1e8.png",
+      "sourceId": "f12a23c4-b924-4322-a260-3d982428f1e8@6c48a",
+      "usedBy": []
+    },
+    {
+      "id": "env_cloud",
+      "kind": "material",
+      "group": "materials",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/mat/env_cloud.mtl",
+      "sourcePackagePath": "assets/materials/env_cloud.mtl",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/mat/env_cloud.mtl",
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/mat/env_cloud.mtl",
+      "sourceId": "aef8d5b0-ab81-4929-9a24-8e16d42f0c35",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/Effect_Evn_Fog/mat/env_cloud.mtl"
+    },
+    {
+      "id": "particle_emitter_v1",
+      "kind": "script",
+      "group": "scripts",
+      "role": "babylon-runtime",
+      "runtimeUse": true,
+      "packagePath": "assets/runtime/particleEmitter.v1.js",
+      "sourcePackagePath": "assets/runtime/particleEmitter.v1.js",
+      "sourceArchivePath": null,
+      "sourcePath": null,
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "02-normalized-vfx",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/02-normalized-vfx.json",
+      "sourcePackagePath": "source/02-normalized-vfx.json",
+      "sourceArchivePath": null,
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/02-normalized-vfx.json",
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "01-source-dump",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/01-source-dump.json",
+      "sourcePackagePath": "source/01-source-dump.json",
+      "sourceArchivePath": null,
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/01-source-dump.json",
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "effect_evn_fog",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/raw/Effect_Evn_Fog.prefab",
+      "sourcePackagePath": "source/raw/Effect_Evn_Fog.prefab",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab",
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab",
+      "sourceId": "34bb52e3-a9a3-45a3-95aa-055fff82e832",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab"
+    },
+    {
+      "id": "effect_evn_fog.meta",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/raw/Effect_Evn_Fog.prefab.meta",
+      "sourcePackagePath": "source/raw/Effect_Evn_Fog.prefab.meta",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab.meta",
+      "sourcePath": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source/cocos/assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab.meta",
+      "sourceId": "34bb52e3-a9a3-45a3-95aa-055fff82e832",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/Effect_Evn_Fog/prefab/Effect_Evn_Fog.prefab.meta"
+    }
+  ],
+  "gcsPrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog",
+  "sourceArchivePrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source",
+  "fullProvenancePrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/provenance",
+  "canonicalSource": "gcs"
+}

package/packages/env.particle.forest_edge_fog/provenance/lineage.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": "vfx-library-lineage/1.0",
+  "savedAt": "2026-05-20T09:28:52.264Z",
+  "sourcePackage": "vfx-intermediate/cocos-babylon-packages/effect_evn_fog",
+  "sourceEffect": "03-effect.json",
+  "libraryPackage": "packages/env.particle.forest_edge_fog",
+  "effectId": "env.particle.forest_edge_fog",
+  "media": {
+    "previewVideo": "media/preview.webm",
+    "previewWebm": "media/preview.webm",
+    "previewMp4": "media/preview.mp4",
+    "previewGif": "media/preview.gif",
+    "thumbnail": "media/thumbnail.png",
+    "gcsUri": null
+  },
+  "recording": {
+    "provider": "browser-mediarecorder",
+    "recordedAt": "2026-05-20T09:28:53.132Z",
+    "mimeType": "video/webm;codecs=vp9",
+    "durationSec": 10,
+    "fps": 30,
+    "media": {
+      "previewVideo": "media/preview.webm",
+      "previewWebm": "media/preview.webm",
+      "previewMp4": "media/preview.mp4",
+      "previewGif": "media/preview.gif",
+      "thumbnail": "media/thumbnail.png",
+      "gcsUri": null
+    }
+  },
+  "description": {
+    "provider": "gemini",
+    "status": "pending_description"
+  },
+  "gcsPrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog",
+  "sourceArchivePrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/source",
+  "fullProvenancePrefix": "gs://fps-vfx-library/packages/env.particle.forest_edge_fog/provenance",
+  "previousIds": [
+    "world.particle.effect_evn_fog"
+  ]
+}

package/packages/generation.ts

@@ -0,0 +1,14 @@
+// 库自有的「生成偏移」参数约定(参数合并第①层),不依赖任何项目。
+import type { VfxParamValues } from './types';
+
+export const VFX_GENERATION_PARAM_KEYS = {
+  offsetX: '__generation.offsetX',
+  offsetY: '__generation.offsetY',
+  offsetZ: '__generation.offsetZ',
+} as const;
+
+export const VFX_DEFAULT_GENERATION_PARAMS: VfxParamValues = {
+  [VFX_GENERATION_PARAM_KEYS.offsetX]: 0,
+  [VFX_GENERATION_PARAM_KEYS.offsetY]: 0,
+  [VFX_GENERATION_PARAM_KEYS.offsetZ]: 0,
+};

package/packages/index.ts

@@ -0,0 +1,14 @@
+// @fps/vfx 库公共入口(纯净:只 re-export 库内模块)
+export * from './types';
+export * from './generation';
+export * from './registry';
+export { VFX_RENDERING_GROUP_ID, configureVfxParticleSystem, configureVfxSpriteManager } from './rendering';
+export { EffectPackageService, type EffectPackageServiceOptions } from './EffectPackageService';
+export { SceneVfxService, type SceneVfxServiceOptions, type SceneVfxWarmupEntry } from './SceneVfxService';
+export {
+  createManifestRuntimeEffectPackage,
+  // 契约命名(plan §4.2):data 包薄包装工厂
+  createManifestRuntimeEffectPackage as createDataDrivenEffectPackage,
+  type ManifestRuntimeEffectPackageOptions,
+} from './manifestRuntimePackage';
+export * from './legacy-particle-runtime';

package/packages/legacy-particle-runtime.ts

@@ -0,0 +1,113 @@
+import { Color4 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture';
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem';
+import type { Scene } from '@babylonjs/core/scene';
+
+interface LegacyParticleRuntimeModule {
+  createParticleEmitterRuntime(args: {
+    BABYLON: typeof LEGACY_BABYLON;
+    scene: Scene;
+    emitter: LegacyParticleEmitterConfig;
+    index?: number;
+    urlForPackagePath: (packagePath: string) => string;
+    shouldStart?: boolean;
+  }): Promise<LegacyParticlePreview>;
+}
+
+export interface LegacyParticleEmitterConfig {
+  name?: string;
+  runtime?: {
+    stopAfterSeconds?: number;
+    disposeOnComplete?: boolean;
+  };
+  [key: string]: unknown;
+}
+
+export interface LegacyParticlePreview {
+  start(): void;
+  stop(): void;
+  dispose(): void;
+  duration: number;
+  system: ParticleSystem;
+}
+
+export interface LegacyParticleRuntimeOptions {
+  scene: Scene;
+  runtimeUrl: string;
+  emitters: LegacyParticleEmitterConfig[];
+  assetUrls: Record<string, string>;
+  onError?: (error: unknown) => void;
+}
+
+const LEGACY_BABYLON = {
+  Color4,
+  Vector3,
+  Texture,
+  ParticleSystem,
+};
+
+export function startLegacyParticleRuntime(options: LegacyParticleRuntimeOptions): { dispose(): void } {
+  let disposed = false;
+  const previews: LegacyParticlePreview[] = [];
+
+  void import(/* @vite-ignore */ options.runtimeUrl)
+    .then((module: LegacyParticleRuntimeModule) => {
+      if (disposed) return;
+      return Promise.all(options.emitters.map((emitter, index) => module.createParticleEmitterRuntime({
+        BABYLON: LEGACY_BABYLON,
+        scene: options.scene,
+        emitter,
+        index,
+        urlForPackagePath: (packagePath) => options.assetUrls[packagePath] ?? packagePath,
+        shouldStart: true,
+      })));
+    })
+    .then((nextPreviews) => {
+      if (!nextPreviews) return;
+      if (disposed) {
+        for (const preview of nextPreviews) preview.dispose();
+        return;
+      }
+      previews.push(...nextPreviews);
+    })
+    .catch((error) => {
+      if (disposed) return;
+      options.onError?.(error);
+    });
+
+  return {
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const preview of previews) preview.dispose();
+      previews.length = 0;
+    },
+  };
+}
+
+export function cloneLegacyEmitters(value: unknown): LegacyParticleEmitterConfig[] {
+  if (!Array.isArray(value)) return [];
+  return JSON.parse(JSON.stringify(value)) as LegacyParticleEmitterConfig[];
+}
+
+export function setNestedValue(target: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let cursor = target;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const key = parts[index];
+    const child = cursor[key];
+    if (!child || typeof child !== 'object' || Array.isArray(child)) {
+      const next: Record<string, unknown> = {};
+      cursor[key] = next;
+      cursor = next;
+    } else {
+      cursor = child as Record<string, unknown>;
+    }
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+
+export function findEmitter(emitters: LegacyParticleEmitterConfig[], name: string): LegacyParticleEmitterConfig | null {
+  return emitters.find(emitter => emitter.name === name) ?? null;
+}