npm - @fps-games/vfx - Versions diffs - 0.3.2 → 0.3.4 - Mend

@fps-games/vfx 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (234) hide show

package/docs/VFX_LIBRARY_ARCHITECTURE_chatgpt.md DELETED Viewed

@@ -1,1580 +0,0 @@
-# VFX Library / 特效库平台设计说明
-> 这份文档用于帮助新进入项目的 Agent 快速理解：我们为什么要做特效库、特效库应该放在哪里、用户如何在 Playable 项目里选择和安装特效、安装后如何在游戏编辑器中调试和保存参数。
----
-## 1. 一句话概括
-我们要做的是一个面向 Playable 制作平台的 **VFX Package Manager + Editor Debug Workflow**。
-它不是一个简单的 `effects/` 文件夹，而是一套让非技术用户和 Agent 都能稳定使用的特效系统：
-```text
-中央特效库
-  ↓
-特效浏览与预览
-  ↓
-添加到当前 Playable 项目
-  ↓
-绑定到对象 / 世界坐标 / Gameplay 事件
-  ↓
-自动打开调试面板
-  ↓
-调参并保存到当前项目或当前实例
-  ↓
-构建时把项目实际使用的特效打包进 Playable
-```
-核心目标是：
-> 让特效像资产一样被浏览、安装、绑定、调试和复用，而不是每次都靠工程师手写 import、手动注册、手动调参数。
----
-## 2. 背景与目标
-Playable 平台面向的是非技术人员。用户希望能通过编辑器或 Agent 快速制作小游戏广告，而不是直接写 Babylon.js 代码。
-在 Playable 中，特效会大量出现在这些场景：
-- 资源收集
-- 金币飞入
-- 解锁区域
-- 建筑升级
-- 车辆尾气
-- 角色移动反馈
-- 引导箭头
-- Endcard 转场
-- 点击反馈
-- 成功 / 失败 / 奖励反馈
-如果每个项目都手动写特效，会出现几个问题：
-1. **复用困难**：同一个“资源收集闪光”在多个项目里反复复制代码。
-2. **导入困难**：新特效需要工程师改代码、注册、打包。
-3. **调试困难**：用户不知道应该在哪里调大小、颜色、粒子数量、挂载位置。
-4. **参数污染**：一个项目里的调参不应该影响中央特效库默认值。
-5. **Agent 难以自动化**：Agent 需要稳定 schema 才能知道有哪些特效、怎么用、怎么验证。
-所以特效库的目标不是单纯管理代码，而是建立一套稳定工作流：
-```text
-发现特效 → 预览特效 → 安装特效 → 使用特效 → 调试特效 → 保存参数 → 构建发布
-```
----
-## 3. 核心原则
-### 3.1 中央库和项目使用必须分离
-中央特效库保存“特效是什么”。
-Playable 项目保存“这个项目安装了哪些特效，以及在哪里使用这些特效”。
-不要让项目调参直接修改中央库默认值。
----
-### 3.2 特效应该是 Package，而不是代码片段
-每个特效都应该有独立 manifest、默认参数、参数 schema、预览图、预览视频和 runtime 入口。
-也就是说，一个特效应该像这样被理解：
-```text
-VFX Package = 实现代码 + 资源 + 参数定义 + 默认值 + 预览信息 + 版本信息
-```
----
-### 3.3 编辑器面板必须 schema-driven
-不要给每个特效单独写一个 React 面板。
-特效包提供 `parameterSchema`，编辑器根据 schema 自动生成滑杆、颜色选择、枚举选择、开关等 UI。
-这样新特效只要声明参数，就能自动被调试面板支持。
----
-### 3.4 Runtime 接口要保持稳定
-Editor 可以有复杂 UI，VFX Library 可以有复杂 registry，但 Runtime 只应该暴露稳定能力：
-```text
-load package
-register package
-play effect
-dispose effect
-```
-不要让 Runtime 直接依赖编辑器产品逻辑。
----
-### 3.5 第一版优先做闭环，不做大而全 marketplace
-MVP 应该优先实现：
-```text
-浏览 → 安装 → 绑定 → 调试 → 保存 → 打包
-```
-暂时不需要一开始就做：
-- 用户上传特效
-- 在线 marketplace
-- 多人协作
-- 复杂依赖解析
-- 自动版本升级
-- 可视化特效节点图
-- 线上热更新
----
-## 4. 四个必须区分的概念
-设计时一定要把下面四个概念分开。
----
-### 4.1 VFX Package
-表示中央库里的一个特效。
-例如：
-```text
-vehicle-exhaust-smoke@1.2.0
-resource-collect-sparkles@1.0.3
-building-upgrade-burst@0.4.1
-```
-它回答的问题是：
-> 这个特效是什么？有哪些参数？需要哪些资源？怎么运行？
----
-### 4.2 VFX Dependency
-表示当前 Playable 项目安装了哪些特效。
-例如：
-```json
-{
-  "vfxDependencies": {
-    "vehicle-exhaust-smoke": "1.2.0",
-    "resource-collect-sparkles": "1.0.3"
-  }
-}
-```
-它回答的问题是：
-> 这个项目依赖哪些特效包？
----
-### 4.3 VFX Usage / Binding
-表示当前 Playable 项目里某个特效被用在哪里。
-例如：
-```text
-Truck 节点挂了 vehicle-exhaust-smoke
-resource.collected 事件触发 resource-collect-sparkles
-UnlockArea 解锁时播放 building-upgrade-burst
-```
-它回答的问题是：
-> 这个特效在当前游戏中什么时候、在哪里、以什么参数播放？
----
-### 4.4 VFX Preview Session
-表示用户现在正在调试某个特效。
-例如：
-```text
-用户正在右侧 Inspector 中调 Truck 尾气的 scale 和 particleCount
-```
-它回答的问题是：
-> 当前面板正在临时预览什么？哪些参数还没有保存？
----
-## 5. 推荐总体架构
-```text
-┌──────────────────────────────┐
-│ VFX Library                  │
-│ 源码、manifest、资源、预览    │
-└──────────────┬───────────────┘
-               │ publish
-               ↓
-┌──────────────────────────────┐
-│ VFX Registry / Asset CDN     │
-│ catalog、版本、bundle、hash   │
-└──────────────┬───────────────┘
-               │ install
-               ↓
-┌──────────────────────────────┐
-│ Playable Project             │
-│ dependencies、lock、presets  │
-└──────────────┬───────────────┘
-               │ load
-               ↓
-┌──────────────────────────────┐
-│ VfxPackageLoader             │
-│ 下载、缓存、动态加载、注册     │
-└──────────────┬───────────────┘
-               ↓
-┌──────────────────────────────┐
-│ EffectPackageService         │
-│ package 注册、查询、参数合并  │
-└──────────────┬───────────────┘
-               ↓
-┌──────────────────────────────┐
-│ SceneVfxService              │
-│ 播放、挂载、追踪、销毁        │
-└──────────────┬───────────────┘
-               ↑
-┌──────────────────────────────┐
-│ Editor VFX Inspector         │
-│ 选择、预览、调参、保存        │
-└──────────────────────────────┘
-```
-一句话：
-> 中央库负责“有哪些特效”，项目负责“安装了哪些特效”，场景和 Gameplay 负责“在哪里、何时使用”，编辑器面板负责“当前正在调什么”。
----
-## 6. 特效库应该放在哪里
-### 6.1 推荐放法
-特效库应该是一个独立逻辑模块或独立 repo。
-推荐目录：
-```text
-vfx-library/
-├── effects/
-│   ├── vehicle-exhaust-smoke/
-│   ├── resource-collect-sparkles/
-│   └── building-upgrade-burst/
-├── registry.json
-├── tooling/
-│   ├── build-effect.ts
-│   ├── validate-manifest.ts
-│   └── publish-effect.ts
-└── README.md
-```
-每个特效是一个独立 package：
-```text
-effects/
-└── vehicle-exhaust-smoke/
-    ├── effect.json
-    ├── src/
-    │   └── index.ts
-    ├── dist/
-    │   └── index.js
-    ├── assets/
-    │   └── smoke.webp
-    ├── presets/
-    │   └── default.json
-    └── previews/
-        ├── thumbnail.webp
-        └── preview.mp4
-```
----
-### 6.2 不推荐放法
-不建议把中央特效库直接放在：
-```text
-某个具体 Playable 项目的 src/
-Babylon 编辑器 repo 的业务 UI 目录里
-Runtime 的 internal assets 目录里
-每个游戏项目里复制一份
-```
-原因：
-- 中央库会被具体项目污染。
-- 项目之间无法统一升级。
-- 构建产物难以去重。
-- Agent 难以知道哪些是平台特效，哪些是项目临时特效。
-- 非技术用户无法形成“可浏览的特效库”心智。
----
-### 6.3 推荐职责边界
-| 层 | 放什么 | 不放什么 |
-|---|---|---|
-| VFX Library | 特效源码、资源、默认参数、schema、预览素材 | 具体项目的调参结果 |
-| VFX Registry / CDN | 编译后的 bundle、manifest、版本、hash、缩略图 | 编辑器业务状态 |
-| Playable Project | 已安装依赖、lock、项目 preset、usage/binding | 整个中央特效源码 |
-| Editor | 特效浏览器、安装按钮、绑定 UI、调试面板 | 每个特效的硬编码面板 |
-| Runtime SDK | 加载、注册、播放、销毁接口 | 产品 UI、registry 页面逻辑 |
----
-## 7. 特效 Package Manifest
-每个特效需要一个 `effect.json`。
-示例：
-```json
-{
-  "schemaVersion": 1,
-  "id": "vehicle-exhaust-smoke",
-  "version": "1.2.0",
-  "displayName": {
-    "zh-CN": "车辆尾气",
-    "en-US": "Vehicle Exhaust Smoke"
-  },
-  "description": {
-    "zh-CN": "适合挂载在车辆尾部的循环烟雾特效。",
-    "en-US": "Looping smoke effect designed for vehicle exhaust."
-  },
-  "category": "vehicle",
-  "tags": ["smoke", "loop", "attachable", "vehicle"],
-  "runtime": {
-    "engine": "babylon",
-    "entry": "./dist/index.js"
-  },
-  "capabilities": {
-    "oneShot": false,
-    "loop": true,
-    "attachable": true,
-    "worldPosition": true,
-    "eventBinding": false
-  },
-  "assets": [
-    "./assets/smoke.webp"
-  ],
-  "preview": {
-    "thumbnail": "./previews/thumbnail.webp",
-    "video": "./previews/preview.mp4"
-  },
-  "defaultParams": {
-    "scale": 1.35,
-    "particleCount": 82,
-    "opacity": 0.6,
-    "color": "#b7b7b7"
-  },
-  "parameterSchema": {
-    "scale": {
-      "type": "number",
-      "label": "整体缩放",
-      "min": 0.05,
-      "max": 8,
-      "step": 0.01,
-      "default": 1.35
-    },
-    "particleCount": {
-      "type": "number",
-      "label": "粒子数量",
-      "min": 1,
-      "max": 300,
-      "step": 1,
-      "default": 82
-    },
-    "opacity": {
-      "type": "number",
-      "label": "透明度",
-      "min": 0,
-      "max": 1,
-      "step": 0.01,
-      "default": 0.6
-    },
-    "color": {
-      "type": "color",
-      "label": "颜色",
-      "default": "#b7b7b7"
-    }
-  },
-  "performance": {
-    "maxParticles": 300,
-    "recommendedInstances": 4
-  },
-  "compatibility": {
-    "runtime": ">=0.1.0",
-    "babylon": ">=6.0.0"
-  }
-}
-```
----
-## 8. 特效 Runtime 接口建议
-特效包最终应该被编译成一个标准模块。
-示例 TypeScript 接口：
-```ts
-export interface VfxEffectPackage<TParams = Record<string, unknown>> {
-  id: string;
-  version: string;
-  create(context: VfxCreateContext, params: TParams): VfxEffectHandle;
-}
-export interface VfxCreateContext {
-  scene: BABYLON.Scene;
-  parent?: BABYLON.Node;
-  position?: BABYLON.Vector3;
-  rotation?: BABYLON.Vector3;
-  assetResolver: VfxAssetResolver;
-}
-export interface VfxEffectHandle {
-  root: BABYLON.Node;
-  dispose(): void;
-  /**
-   * 可选。第一版不强制。
-   * 如果某些循环特效需要不重建就实时调参，可以后续支持。
-   */
-  updateParams?: (patch: Record<string, unknown>) => void;
-}
-```
-第一版不要求每个特效实现 `updateParams`。
-调参时可以采用：
-```text
-参数变化
-  ↓
-debounce 50-100ms
-  ↓
-dispose 当前预览
-  ↓
-用新参数重新 create
-```
-好处：
-- 所有特效都能支持。
-- Runtime 接口简单。
-- 调试结果确定。
-- 更容易做自动截图回归。
----
-## 9. 用户如何“选中特效”
-这里有两个不同语义的“选中”，必须分开设计。
----
-### 9.1 从中央库中选中 VFX Package
-用户在编辑器里打开特效库：
-```text
-资产
-  ├── 模型
-  ├── UI
-  ├── 音效
-  └── 特效
-```
-特效库以卡片形式展示：
-```text
-┌──────────────────────┐
-│ thumbnail / video    │
-│ 车辆尾气              │
-│ 循环 / 可挂载          │
-│ [预览] [添加到项目]    │
-└──────────────────────┘
-```
-点击卡片后右侧显示：
-```text
-特效名称
-预览视频
-使用说明
-分类 / 标签
-参数列表
-性能预算
-版本信息
-[添加到项目]
-[绑定到当前选中对象]
-[放到场景中]
-```
-此时选中的是：
-```text
-VFX Package
-```
-用户还没有真正修改当前游戏。
----
-### 9.2 从当前项目中选中 VFX Usage
-特效添加到项目并使用后，它应该成为当前项目里的一个对象或绑定。
-例如：
-```text
-Scene
-├── Truck
-│   ├── Model
-│   └── VFX: Vehicle Exhaust
-├── Player
-└── Gameplay Bindings
-    └── On Resource Collected
-        └── VFX: Collect Sparkles
-```
-此时选中的是：
-```text
-VFX Usage / Binding
-```
-右侧 Inspector 应该打开当前实例的调试面板。
----
-## 10. 特效如何添加到项目
-### 10.1 安装流程
-用户点击“添加到项目”后，推荐流程：
-```text
-用户点击“添加到项目”
-  ↓
-读取 package id 和 version
-  ↓
-检查项目是否已经安装
-  ↓
-从 registry 下载或读取缓存
-  ↓
-写入 project.vfxDependencies
-  ↓
-写入 vfx-lock.json
-  ↓
-动态加载 package bundle
-  ↓
-注册到 EffectPackageService
-  ↓
-创建 Preview Session 或 VFX Usage
-  ↓
-编辑器自动选中新建对象
-  ↓
-右侧自动打开 VFX Inspector
-```
----
-### 10.2 项目 dependency 示例
-可以放在项目配置中：
-```json
-{
-  "vfxDependencies": {
-    "vehicle-exhaust-smoke": "1.2.0",
-    "resource-collect-sparkles": "1.0.3"
-  }
-}
-```
----
-### 10.3 lock 文件示例
-```json
-{
-  "packages": {
-    "vehicle-exhaust-smoke@1.2.0": {
-      "resolved": "https://registry.example.com/vfx/vehicle-exhaust-smoke/1.2.0/index.js",
-      "integrity": "sha256-xxxxxxxx",
-      "assets": [
-        {
-          "path": "assets/smoke.webp",
-          "integrity": "sha256-yyyyyyyy"
-        }
-      ]
-    }
-  }
-}
-```
-项目依赖负责表达：
-```text
-我需要哪个特效
-```
-lock 文件负责表达：
-```text
-我实际用了哪个 bundle、哪个资源、哪个 hash
-```
----
-## 11. 三种核心使用方式
-第一版建议优先支持三种使用方式。
----
-### 11.1 放到世界坐标
-适合：
-- 爆炸
-- 区域解锁
-- 建筑升级
-- 地面光圈
-- 奖励出现
-数据示例：
-```json
-{
-  "id": "vfx_usage_unlock_burst_01",
-  "type": "world",
-  "package": "building-upgrade-burst@0.4.1",
-  "position": [2.5, 0.1, -3.2],
-  "rotation": [0, 0, 0],
-  "params": {
-    "scale": 1.2
-  }
-}
-```
----
-### 11.2 挂到场景对象
-适合：
-- 车辆尾气
-- 角色脚步烟尘
-- 建筑光环
-- 目标提示
-- NPC 状态反馈
-数据示例：
-```json
-{
-  "id": "vfx_usage_truck_exhaust",
-  "type": "attachment",
-  "package": "vehicle-exhaust-smoke@1.2.0",
-  "targetNodeId": "truck_01",
-  "transform": {
-    "position": [0, 0.4, -1.2],
-    "rotation": [0, 3.14, 0],
-    "scale": [1, 1, 1]
-  },
-  "params": {
-    "scale": 1.1,
-    "particleCount": 64
-  }
-}
-```
----
-### 11.3 绑定 Gameplay Event
-适合：
-- 资源收集
-- 金币飞入
-- 购买成功
-- 解锁完成
-- 任务完成
-- Endcard 触发
-数据示例：
-```json
-{
-  "id": "vfx_binding_collect_wood",
-  "type": "eventBinding",
-  "package": "resource-collect-sparkles@1.0.3",
-  "trigger": {
-    "event": "resource.collected",
-    "filter": {
-      "resourceType": "wood"
-    }
-  },
-  "spawn": {
-    "source": "event.position"
-  },
-  "params": {
-    "scale": 0.9
-  }
-}
-```
----
-## 12. 添加后如何自动打开调试面板
-编辑器需要一个统一 selection 事件。
-示例：
-```ts
-editorSelection.select({
-  type: 'vfx-usage',
-  id: usageId
-});
-```
-Inspector 根据 selection 类型切换面板：
-```ts
-if (selection.type === 'vfx-usage') {
-  openInspectorTab('vfx');
-}
-```
-推荐用户体验：
-```text
-用户选中 Truck
-  ↓
-打开特效库
-  ↓
-点击“绑定到当前对象”
-  ↓
-系统创建 VfxAttachment
-  ↓
-自动选中新建的 VfxAttachment
-  ↓
-右侧打开 VFX Inspector
-  ↓
-自动开始循环预览
-```
-对于事件型特效：
-```text
-用户选择 resource.collected 事件
-  ↓
-点击“添加收集特效”
-  ↓
-创建 VfxEventBinding
-  ↓
-右侧打开 VFX Inspector
-  ↓
-面板显示“播放一次”按钮
-```
-关键点：
-> 添加特效后，用户不应该再去层级树里手动找它。系统应该自动选中并打开对应调试面板。
----
-## 13. VFX Inspector 设计
-VFX Inspector 是通用调试面板。
-它不应该写死某个特效的 UI，而应该读取 manifest 的 `parameterSchema` 自动生成控件。
-推荐面板结构：
-```text
-车辆尾气
-Package
-  ID: vehicle-exhaust-smoke
-  Version: 1.2.0
-Preview
-  [播放] [暂停] [重播]
-  [隔离预览] [游戏内预览]
-Target
-  Type: Attachment
-  Target: Truck
-  Position: X / Y / Z
-  Rotation: X / Y / Z
-  Scale: X / Y / Z
-Parameters
-  整体缩放      [----●-----]
-  粒子数量      [------●---]
-  透明度        [---●------]
-  颜色          [■]
-Save
-  [保存到当前实例]
-  [保存为项目 Preset]
-  [另存为新 Variant]
-```
----
-## 14. 两种预览模式
-### 14.1 隔离预览
-在统一 preview stage 中预览特效。
-特点：
-- 标准相机
-- 标准光照
-- 标准地面
-- 标准角色或车辆参照物
-- 自动循环
-- 适合浏览和比较特效
-用于回答：
-> 这个特效大概长什么样？
----
-### 14.2 游戏内预览
-在当前 Playable 场景中，以当前对象、当前相机、当前光照播放特效。
-特点：
-- 看到真实大小
-- 看到真实遮挡关系
-- 看到与当前资产的颜色是否搭配
-- 看到相机距离下是否清晰
-- 适合最终调参
-用于回答：
-> 这个特效放到我的游戏里是否合适？
----
-## 15. 参数保存层设计
-参数保存层是整个特效系统中非常关键的部分。
-不要让用户在项目里调参时直接覆盖中央库默认值。
-推荐优先级：
-```text
-1. Library Default
-   中央库默认值，只读
-2. Published Preset
-   中央库发布的官方预设，只读
-3. Project Preset
-   当前 Playable 项目级预设
-4. Usage Override
-   当前对象或事件绑定的实例级覆盖
-5. Runtime Override
-   Gameplay 运行时根据上下文传入
-6. Preview Session Override
-   面板临时调试值，尚未保存
-```
-参数合并顺序：
-```text
-Library Default
-  ↓
-Published Preset
-  ↓
-Project Preset
-  ↓
-Usage Override
-  ↓
-Runtime Override
-  ↓
-Preview Session Override
-```
-用户保存时必须明确选择保存位置：
-```text
-保存到当前实例
-保存为项目 Preset
-发布为新的公共 Variant
-```
-第一版建议只实现：
-```text
-保存到当前实例
-保存为项目 Preset
-```
-“发布为公共 Variant”可以留到后面。
----
-## 16. 项目内数据结构建议
-一个 Playable 项目中建议有三类 VFX 数据。
----
-### 16.1 dependencies
-表示项目安装了哪些特效。
-```json
-{
-  "vfxDependencies": {
-    "vehicle-exhaust-smoke": "1.2.0",
-    "resource-collect-sparkles": "1.0.3"
-  }
-}
-```
----
-### 16.2 usages
-表示场景中有哪些特效实例。
-```json
-{
-  "vfxUsages": [
-    {
-      "id": "vfx_usage_truck_exhaust",
-      "type": "attachment",
-      "package": "vehicle-exhaust-smoke@1.2.0",
-      "targetNodeId": "truck_01",
-      "transform": {
-        "position": [0, 0.4, -1.2],
-        "rotation": [0, 3.14, 0],
-        "scale": [1, 1, 1]
-      },
-      "params": {
-        "scale": 1.1
-      }
-    }
-  ]
-}
-```
----
-### 16.3 eventBindings
-表示 Gameplay 事件触发哪些特效。
-```json
-{
-  "vfxEventBindings": [
-    {
-      "id": "vfx_binding_collect_wood",
-      "type": "eventBinding",
-      "package": "resource-collect-sparkles@1.0.3",
-      "trigger": {
-        "event": "resource.collected",
-        "filter": {
-          "resourceType": "wood"
-        }
-      },
-      "spawn": {
-        "source": "event.position"
-      },
-      "params": {
-        "scale": 0.9
-      }
-    }
-  ]
-}
-```
----
-## 17. Runtime 加载流程
-推荐新增一个 `VfxPackageLoader`。
-职责：
-```ts
-interface VfxPackageLoader {
-  install(packageRef: VfxPackageRef): Promise<VfxInstalledPackage>;
-  load(packageRef: VfxPackageRef): Promise<VfxEffectPackage>;
-  unload(packageId: string): void;
-  getLoaded(packageId: string): VfxEffectPackage | null;
-}
-```
-加载流程：
-```text
-读取 project.vfxDependencies
-  ↓
-读取 vfx-lock.json
-  ↓
-下载或读取本地缓存
-  ↓
-动态 import package entry
-  ↓
-加载 package assets
-  ↓
-构造 VfxEffectPackage
-  ↓
-EffectPackageService.register(package)
-```
-播放流程：
-```text
-SceneVfxService.playEffectPackage(packageId, params, target)
-  ↓
-EffectPackageService 查找 package
-  ↓
-合并参数
-  ↓
-调用 package.create(...)
-  ↓
-得到 handle
-  ↓
-记录 handle
-  ↓
-需要时 dispose
-```
----
-## 18. 构建与发布
-开发态可以动态加载特效。
-但最终导出的 Playable 不应该依赖远程 registry。
-构建时应该：
-```text
-读取项目 vfxDependencies
-  ↓
-读取 usage / eventBindings，确认实际使用的特效
-  ↓
-收集对应 bundle 和 assets
-  ↓
-tree-shake 未使用特效
-  ↓
-把必要资源打入最终 Playable 包
-  ↓
-生成 runtime manifest
-```
-构建目标：
-- 最终包里只包含当前项目实际用到的特效。
-- 不把整个中央库打进去。
-- 不在广告运行时请求远程特效资源。
-- 构建结果可复现。
-- lock 文件能保证同一个项目重复构建结果一致。
----
-## 19. Agent 应该如何操作特效系统
-新 Agent 进入项目后，应该按这个顺序理解特效系统：
-1. 先读中央库 `registry.json`，知道有哪些特效。
-2. 再读每个特效的 `effect.json`，知道它的参数和能力。
-3. 再读当前 Playable 项目的 `vfxDependencies`，知道项目安装了哪些特效。
-4. 再读当前项目的 `vfxUsages` 和 `vfxEventBindings`，知道特效实际用在哪里。
-5. 如果要改视觉效果，优先改 usage override 或 project preset。
-6. 不要直接修改中央库默认参数，除非任务明确要求发布新的 library default。
-7. 如果新增特效，要补齐 manifest、preview、defaultParams、parameterSchema 和简单验证。
-8. 如果新增参数，要确保 Inspector 可以通过 schema 自动生成控件。
-9. 如果改 Runtime 接口，要尽量保持向后兼容。
-10. 修改完成后要能通过编辑器预览或自动截图验证。
----
-## 20. MVP 建议
-第一版只做最小闭环。
-### 20.1 必做
-```text
-中央静态 registry.json
-  ↓
-编辑器显示特效卡片
-  ↓
-支持隔离预览
-  ↓
-添加到项目
-  ↓
-写入 vfxDependencies
-  ↓
-动态加载并注册
-  ↓
-绑定到对象或放到世界坐标
-  ↓
-自动打开 VFX Inspector
-  ↓
-根据 parameterSchema 调参
-  ↓
-保存为 usage override
-  ↓
-构建时打包已安装特效
-```
----
-### 20.2 第一版支持的特效类型
-优先支持三类：
-```text
-1. world
-   放在世界坐标
-2. attachment
-   挂在场景对象上
-3. eventBinding
-   绑定 Gameplay 事件
-```
----
-### 20.3 第一版暂不做
-```text
-用户上传特效
-公开 marketplace
-自动版本升级
-复杂依赖解析
-多人协作
-公共 Variant 发布流
-可视化特效节点编辑器
-所有参数实时 updateParams
-线上热更新
-```
----
-## 21. 关键 UI 流程
-### 21.1 浏览并添加特效
-```text
-打开资产面板
-  ↓
-进入“特效”
-  ↓
-浏览卡片
-  ↓
-点击特效
-  ↓
-查看预览和参数
-  ↓
-点击“添加到项目”
-  ↓
-项目安装依赖
-  ↓
-右侧提示安装成功
-```
----
-### 21.2 绑定到当前对象
-```text
-选中 Truck
-  ↓
-打开特效库
-  ↓
-选择“车辆尾气”
-  ↓
-点击“绑定到当前对象”
-  ↓
-创建 VfxAttachment
-  ↓
-自动选中该 VFX Usage
-  ↓
-右侧打开 VFX Inspector
-  ↓
-自动游戏内预览
-```
----
-### 21.3 绑定到 Gameplay 事件
-```text
-打开 Gameplay 面板
-  ↓
-选择 resource.collected 事件
-  ↓
-点击“添加特效”
-  ↓
-选择 resource-collect-sparkles
-  ↓
-创建 VfxEventBinding
-  ↓
-打开 Inspector
-  ↓
-点击“播放一次”验证
-  ↓
-保存参数
-```
----
-### 21.4 调参并保存
-```text
-用户拖动参数滑杆
-  ↓
-Preview Session 更新
-  ↓
-重建或更新当前预览
-  ↓
-用户满意
-  ↓
-点击“保存到当前实例”
-  ↓
-写入 usage.params
-```
----
-## 22. 常见设计陷阱
-### 22.1 把中央库默认值和项目参数混在一起
-错误：
-```text
-用户在某个项目里调了车辆尾气
-  ↓
-直接写回 vehicle-exhaust-smoke/effect.json
-```
-这样会污染所有项目。
-正确：
-```text
-中央默认值只读
-项目调参写入 usage override 或 project preset
-```
----
-### 22.2 用硬编码 UI 调每个特效
-错误：
-```text
-VehicleExhaustPanel.tsx
-CollectSparklesPanel.tsx
-UpgradeBurstPanel.tsx
-```
-正确：
-```text
-统一 VFX Inspector
-  ↓
-读取 parameterSchema
-  ↓
-自动生成 UI
-```
----
-### 22.3 添加后不自动选中
-错误体验：
-```text
-用户添加特效
-  ↓
-系统说添加成功
-  ↓
-用户不知道在哪里调
-```
-正确体验：
-```text
-用户添加特效
-  ↓
-系统自动创建 usage
-  ↓
-自动选中
-  ↓
-自动打开 VFX Inspector
-```
----
-### 22.4 把整个中央库打进最终 Playable
-错误：
-```text
-最终包包含所有特效
-```
-正确：
-```text
-最终包只包含当前项目使用的特效
-```
----
-### 22.5 第一版把版本系统做得太复杂
-第一版可以只支持：
-```text
-固定版本安装
-lock 文件锁定
-手动升级
-```
-不要一开始做复杂 peer dependency、自动升级、兼容迁移。
----
-## 23. 推荐开发顺序
-### Phase 1：本地静态特效库
-目标：
-```text
-有一个 registry.json，编辑器能展示特效卡片。
-```
-任务：
-- 定义 `effect.json` schema。
-- 搭建 `vfx-library/effects/*` 目录。
-- 写 2-3 个示例特效。
-- 为每个特效补 thumbnail 和 defaultParams。
-- 编辑器读取 registry 并显示卡片。
----
-### Phase 2：安装到项目
-目标：
-```text
-点击“添加到项目”可以写入 project.vfxDependencies。
-```
-任务：
-- 定义 project dependency schema。
-- 定义 lock 文件。
-- 实现 `VfxPackageInstaller`。
-- 实现已安装状态展示。
-- 避免重复安装。
----
-### Phase 3：Runtime 动态加载和注册
-目标：
-```text
-项目安装的特效可以被 Runtime 加载并播放。
-```
-任务：
-- 实现 `VfxPackageLoader`。
-- 支持动态 import。
-- 支持 assets resolve。
-- 加载后注册到 `EffectPackageService`。
-- 通过 `SceneVfxService` 播放。
----
-### Phase 4：编辑器绑定和 Inspector
-目标：
-```text
-用户可以把特效绑定到对象，自动打开调试面板。
-```
-任务：
-- 定义 `vfxUsages`。
-- 支持 world usage。
-- 支持 attachment usage。
-- 接入 editor selection。
-- 实现通用 VFX Inspector。
-- 根据 parameterSchema 生成控件。
-- 支持保存到 usage override。
----
-### Phase 5：Gameplay Event Binding
-目标：
-```text
-Gameplay 事件可以触发特效。
-```
-任务：
-- 定义 `vfxEventBindings`。
-- 支持常见事件：collect、unlock、upgrade、purchase、endcard。
-- 支持 event.position / target.node 等 spawn source。
-- Inspector 支持“播放一次”测试。
-- Runtime 事件系统触发对应特效。
----
-### Phase 6：构建打包
-目标：
-```text
-发布 Playable 时只打包当前项目使用的特效和资源。
-```
-任务：
-- 构建阶段读取 dependencies 和 usages。
-- 收集 bundle 和 assets。
-- 生成 runtime manifest。
-- 检查包体大小。
-- 检查缺失资源。
-- 保证离线可运行。
----
-## 24. 判断一个特效功能是否“平台化”的检查项
-一个特效真正平台化，需要满足：
-- [ ] 有唯一 ID。
-- [ ] 有版本。
-- [ ] 有 manifest。
-- [ ] 有默认参数。
-- [ ] 有参数 schema。
-- [ ] 有预览图或预览视频。
-- [ ] 能被 registry 发现。
-- [ ] 能被安装到项目。
-- [ ] 能被 Runtime 加载。
-- [ ] 能通过统一服务播放。
-- [ ] 能被挂到对象或事件。
-- [ ] 能在 Inspector 中调参。
-- [ ] 调参结果不会污染中央默认值。
-- [ ] 构建时能被打包进最终 Playable。
-- [ ] 未使用时不会进入最终包。
-- [ ] Agent 能通过 schema 理解怎么使用它。
----
-## 25. 名词表
-| 名词 | 含义 |
-|---|---|
-| VFX Package | 一个可复用特效包，包括代码、资源、参数 schema、默认值和预览信息 |
-| VFX Registry | 特效目录，记录有哪些特效、版本、入口和预览信息 |
-| VFX Dependency | 当前 Playable 项目安装的特效依赖 |
-| VFX Lock | 锁定实际 bundle、资源和 hash 的文件 |
-| VFX Usage | 当前项目中某个特效实例的使用记录 |
-| VFX Event Binding | 某个 Gameplay 事件和特效之间的绑定 |
-| VFX Preview Session | 当前编辑器里正在调试的临时状态 |
-| Parameter Schema | 用于自动生成调参 UI 的参数定义 |
-| Usage Override | 当前实例上的参数覆盖 |
-| Project Preset | 当前项目级别的参数预设 |
-| Library Default | 中央特效库提供的默认参数 |
-| SceneVfxService | Runtime 中负责播放、追踪和销毁特效的服务 |
-| EffectPackageService | Runtime 中负责注册和查询特效包的服务 |
-| VfxPackageLoader | 负责加载、缓存和注册特效 package 的模块 |
----
-## 26. 最终方向总结
-特效库的核心不是“把特效代码放在哪个目录”，而是建立一套从中央库到项目使用的完整产品链路。
-推荐方向：
-```text
-中央 VFX Library
-  负责生产和维护特效 package
-VFX Registry
-  负责让编辑器发现特效
-Playable Project
-  负责记录安装依赖和项目使用
-Runtime Loader
-  负责加载和注册 package
-SceneVfxService
-  负责播放和生命周期
-Editor VFX Inspector
-  负责选择、预览、调参和保存
-```
-第一版最重要的是跑通这个闭环：
-```text
-选择特效
-  ↓
-添加到项目
-  ↓
-绑定到对象或事件
-  ↓
-自动打开调试面板
-  ↓
-调参
-  ↓
-保存到当前实例
-  ↓
-构建进最终 Playable
-```
-只要这条链路稳定，后续再做 marketplace、用户上传、公共 variant、自动推荐、Agent 自动调参都会比较自然。